Módulo de Minijuegos

Información general

El MiniGamesModule proporciona acceso programático a las experiencias de minijuegos de los jugadores. Actualmente expone un método público para generar una URL de lanzamiento segura y con límite de tiempo que se puede representar en un iframe para el jugador autenticado.

Este documento cubre todos los miembros públicos actualmente disponibles en src/modules/mini-games/mini-games.module.ts y las interfaces/tipos públicos directamente relacionados con esos miembros.

---

Clase: MiniGamesModule

Acceso al módulo (sin inicialización manual)

El MiniGamesModule no requiere construcción o inicialización directa. Accédalo a través del singleton principal del SDK:

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

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

O desestructúrelo directamente de la instancia:

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

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

Notas:

• No llame new MiniGamesModule(...) directamente; el SDK administra su ciclo de vida y dependencias.
• La instancia del SDK encapsula el contexto del jugador autenticado utilizado por el módulo para las solicitudes.

---

Métodos

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

Genera una URL de lanzamiento para la recompensa de minijuego de un jugador. Utilice esta URL para representar la experiencia del minijuego dentro de un iframe para el jugador autenticado actualmente.

Parámetros:

• miniGameOfferId (string): El identificador único de la oferta de minijuego para lanzar para el jugador.
• uniqueIdentifier (string): Un identificador único asociado con esta solicitud de lanzamiento específica. Generalmente esto proviene de la recompensa otorgada al jugador y se usa en el backend para correlacionar y validar el lanzamiento.

Devuelve:

• Promise<SimpleResponse<{ url: string }>> — Un envoltorio de respuesta asincrónica con uno de los siguientes resultados:
  • En caso de éxito (ok: true): data contiene un objeto con la URL de lanzamiento generada, por ejemplo { url: "https://..." }.
  • En caso de fallo (ok: false): data es null y error contiene detalles estructurados sobre el fallo.

Las posibles causas de error incluyen identificadores no válidos, falta de contexto del jugador o fallos de validación del backend. Consulte ErrorResponse para conocer la estructura del error.

Ejemplo:

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

if (response.ok && response.data) {
  const { url } = response.data;
  // Representar en un iframe o redirigir
  // iframe.src = url;
} else {
  console.error("No se pudo generar la URL de lanzamiento", response.error);
}

---

Interfaces y tipos

Las siguientes interfaces públicas del módulo principal se utilizan por MiniGamesModule y son relevantes al consumir su API.

SimpleResponse<T>

interface SimpleResponse<T> {
  ok: boolean;
  error?: ErrorResponse;
  data: T | null;
}

• ok (boolean): Indica si la operación tuvo éxito.
• error (ErrorResponse | undefined): Presente cuando ok es false. Contiene detalles sobre el fallo.
• data (T | null): La carga útil exitosa cuando ok es true; de lo contrario null.

Para generatePlayerMiniGameRewardLaunchUrl, T es { 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): Resumen de error legible por humanos.
• details.faultCode (number): Código proporcionado por el backend que identifica el tipo de error.
• details.fields ({ field: string; error: string; }[]): Problemas de validación a nivel de campo, cuando corresponda.
• request.xRequestId (string): Identificador de correlación para rastrear la solicitud.
• request.method (string): Método HTTP utilizado en la solicitud fallida.
• request.headers (Record<string, string>[]): Encabezados seleccionados capturados para diagnóstico.
• timestamp (string): Marca de tiempo ISO-8601 de cuándo se produjo el error.

---

Cargas de respuesta

Para generatePlayerMiniGameRewardLaunchUrl en caso de éxito:

{ url: string }

• url (string): La URL completamente calificada para cargar el mini-juego en un iframe para el jugador autenticado.