MiniGames: MiniGamesModule

Visão geral

O MiniGamesModule fornece acesso programático a experiências de mini‑jogos do jogador. Atualmente, ele expõe um método público para gerar um URL de lançamento seguro e com prazo limitado que pode ser renderizado em um iframe para o jogador autenticado.

Este documento abrange todos os membros públicos atualmente disponíveis em src/modules/mini-games/mini-games.module.ts e as interfaces/tipos públicos diretamente relacionados a esses membros.

---

MiniGames: MiniGamesModule`

Acessando o módulo (sem inicialização manual)

O MiniGamesModule não requer construção ou inicialização direta. Acesse-o por meio do singleton principal do SDK:

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

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

Ou faça a desestruturação diretamente a partir da instância:

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

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

Observações:

• Não chame new MiniGamesModule(...) diretamente; o SDK gerencia seu ciclo de vida e dependências.
• A instância do SDK encapsula o contexto do jogador autenticado usado pelo módulo para solicitações.

---

Métodos

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

Generates a launch URL for a player's mini‑game reward. Use esta URL para renderizar a experiência do mini‑jogo dentro de um iframe para o jogador atualmente autenticado.

Parâmetros:

• miniGameOfferId (string): O identificador exclusivo da oferta de mini‑jogo a ser lançada para o jogador.
• uniqueIdentifier (string): Um identificador exclusivo associado a esta solicitação de lançamento específica. Normalmente, isso vem da recompensa concedida ao jogador e é usado pelo back-end para correlacionar e validar o lançamento.

Retornos:

• Promise<SimpleResponse<{ url: string }>> — Um envoltório de resposta assíncrona com um dos seguintes resultados:
  • Em caso de sucesso (ok: true): data contém um objeto com o URL de lançamento gerado, por exemplo, { url: "https://..." }.
  • Em caso de falha (ok: false): data é null e error contém detalhes estruturados sobre a falha.

As possíveis causas de erro incluem identificadores inválidos, contexto de jogador ausente ou falhas de validação do back-end. Consulte ErrorResponse para obter a estrutura de erro.

Exemplo:

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

if (response.ok && response.data) {
  const { url } = response.data;
  // Renderizar em um iframe ou redirecionar
  // iframe.src = url;
} else {
  console.error("Falha ao gerar URL de lançamento", response.error);
}

---

Interfaces e Tipos

As seguintes interfaces públicas do módulo principal são usadas pelo MiniGamesModule e são relevantes ao consumir sua API.

SimpleResponse<T>

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

• ok (boolean): Indica se a operação foi bem-sucedida.
• error (ErrorResponse | undefined): Presente quando ok é false. Contém detalhes sobre a falha.
• data (T | null): A carga útil bem-sucedida quando ok é true; caso contrário, null.

Para generatePlayerMiniGameRewardLaunchUrl, T é { 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): Resumo de erro legível por humanos.
• details.faultCode (number): Código fornecido pelo back-end que identifica o tipo de erro.
• details.fields ({ field: string; error: string; }[]): Problemas de validação no nível de campo, quando aplicável.
• request.xRequestId (string): Identificador de correlação para rastrear a solicitação.
• request.method (string): Método HTTP usado na solicitação com falha.
• request.headers (Record<string, string>[]): Cabeçalhos selecionados capturados para diagnóstico.
• timestamp (string): Timestamp ISO‑8601 de quando o erro ocorreu.

---

Payloads de resposta

Para generatePlayerMiniGameRewardLaunchUrl com sucesso:

{url: string}

• url (string): A URL totalmente qualificada para carregar o mini‑game em um iframe para o jogador autenticado.