Skip to main content

MiniGames Module

Overview​

The MiniGamesModule provides programmatic access to player mini‑game experiences. It currently exposes one public method to generate a secure, time‑bound launch URL that can be rendered in an iframe for the authenticated player.

This document covers all public members currently available in src/modules/mini-games/mini-games.module.ts and the public interfaces/types directly related to those members.

Class: MiniGamesModule​

Accessing the module (no manual initialization)​

The MiniGamesModule does not require direct construction or initialization. Access it via the main SDK singleton:

import { GamanzaEngageWebClientSDK } from '@gamanza/engage-web-client-sdk';

const sdk = GamanzaEngageWebClientSDK.getInstance();
const miniGames = sdk.MiniGames;

Or destructure directly from the instance:

import { GamanzaEngageWebClientSDK } from '@gamanza/engage-web-client-sdk';

const { MiniGames: miniGames } = GamanzaEngageWebClientSDK.getInstance();

Notes:

  • Do not call new MiniGamesModule(...) directly; the SDK manages its lifecycle and dependencies.
  • The SDK instance encapsulates the authenticated player context used by the module for requests.

Methods​

generatePlayerMiniGameRewardLaunchUrl(miniGameOfferId: string, uniqueIdentifier: string): Promise<SimpleResponse<{ url: string }>>​

Generates a launch URL for a player’s mini‑game reward. Use this URL to render the mini‑game experience inside an iframe for the currently authenticated player.

Parameters:

  • miniGameOfferId (string): The unique identifier of the mini‑game offer to launch for the player.
  • uniqueIdentifier (string): A unique identifier associated with this specific launch request. Typically this comes from the reward granted to the player and is used by the backend to correlate and validate the launch.

Returns:

  • Promise<SimpleResponse<{ url: string }>> — An asynchronous response wrapper with one of the following outcomes:
    • On success (ok: true): data contains an object with the generated launch URL, e.g. { url: "https://..." }.
    • On failure (ok: false): data is null and error contains structured details about the failure.

Possible error causes include invalid identifiers, missing player context, or backend validation failures. See ErrorResponse for the error structure.

Example:

const response = await miniGames.generatePlayerMiniGameRewardLaunchUrl(
  "offer_123",
  "rewardGrant_456"
);

if (response.ok && response.data) {
  const { url } = response.data;
  // Render in an iframe or redirect
  // iframe.src = url;
} else {
  console.error("Failed to generate launch URL", response.error);
}

Interfaces and Types​

The following public interfaces from the core module are used by MiniGamesModule and are relevant when consuming its API.

SimpleResponse<T>​

interface SimpleResponse<T> {
  ok: boolean;
  error?: ErrorResponse;
  data: T | null;
}
  • ok (boolean): Indicates whether the operation succeeded.
  • error (ErrorResponse | undefined): Present when ok is false. Contains details about the failure.
  • data (T | null): The successful payload when ok is true; otherwise null.

For generatePlayerMiniGameRewardLaunchUrl, T is { url: string }.

ErrorResponse​

interface ErrorResponse {
  message: string;
  details: {
    faultCode: number;
    fields: {
      field: string;
      error: string;
    }[];
  };
  request: {
    xRequestId: string;
    method: string;
    headers: Record<string, string>[];
  };
  timestamp: string;
}
  • message (string): Human‑readable error summary.
  • details.faultCode (number): Backend‑provided code identifying the error type.
  • details.fields ({ field: string; error: string; }[]): Field‑level validation issues, when applicable.
  • request.xRequestId (string): Correlation identifier for tracing the request.
  • request.method (string): HTTP method used in the failing request.
  • request.headers (Record<string, string>[]): Select headers captured for diagnostics.
  • timestamp (string): ISO‑8601 timestamp of when the error occurred.

Response Payloads​

For generatePlayerMiniGameRewardLaunchUrl on success:

{ url: string }
  • url (string): The fully qualified URL to load the mini‑game in an iframe for the authenticated player.