Pular para o conteúdo principal
Gamanza Engages

Gamanza Engage Web Client SDK

Visão geral

O Gamanza Engage Web Client SDK permite que desenvolvedores criem interfaces de usuário ricas e personalizáveis que se integram perfeitamente com a Plataforma Gamanza Engage. Projetado para flexibilidade e desempenho, este SDK fornece uma interface estruturada e modular para interagir com recursos de engajamento importantes, como perfis de jogadores, missões, torneios, recompensas e muito mais.

Ao aproveitar este SDK, você pode:

  • Acessar dados e eventos em tempo real para o jogador autenticado.
  • Ouvir atualizações ao vivo da Plataforma de Engajamento de Jogadores Gamanza.
  • Construir componentes personalizados de fidelidade e gamificação adequados às necessidades do seu produto.
  • Manter uma integração limpa e consistente usando uma arquitetura baseada em singleton.

Seja você está construindo do zero ou aprimorando um frontend existente, o SDK simplifica a comunicação com a API frontend Gamanza Engage, ajudando você a entregar experiências envolventes com facilidade e eficiência.

Início rápido

Antes de começar

  1. Entenda as APIs que você precisa implementar
  2. Crie um ID de cliente
  3. Configure a autenticação

Instalar o SDK

npm install --save @gamanza-engage/web-client-sdk

Usando o SDK

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

export const initSDK = async () => {
await GamanzaEngageWebClientSDK.init({
clientId: 'seu id de cliente',
identityToken: 'token de identidade do jogador',
serviceUrl: '[https://fontend-api-[sua-instância].gamanzaengage.com]'
});

const { Player } = GamanzaEngageWebClientSDK.getInstance();
const playerInfo = await Player.getPlayer();
console.log(playerInfo);
}

Métodos estáticos

init(config: AuthConfig): Promise<GamanzaEngageWebClientSDK>

Inicializa o SDK com a configuração de autenticação fornecida. Este método deve ser chamado antes de usar qualquer funcionalidade do SDK.

Parâmetros:

  • config (AuthConfig): Objeto de configuração de autenticação contendo:
    • clientId (string): ID do cliente gerado na sua Instância Administrativa Gamanza Engage
    • identityToken (string): O token de identidade para autenticação
    • serviceUrl (string): O URL base para o serviço Gamanza Engage

Retorna:

  • Promise<GamanzaEngageWebClientSDK>: Uma promessa que é resolvida para a instância do SDK inicializada

Exemplo:

const config = {
clientId: 'seu-id-de-cliente',
identityToken: 'seu-token-de-identidade',
serviceUrl: '[https://fontend-api-[sua-instância].gamanzaengage.com]'
};
const sdk = await GamanzaEngageWebClientSDK.init(config);

getInstance(): GamanzaEngageWebClientSDK

Retorna a instância singleton do SDK. O SDK deve ser inicializado usando init() antes de chamar este método.

Retorna:

  • GamanzaEngageWebClientSDK: A instância singleton do SDK

Lança:

  • SDKNotInitializedException: Quando chamado antes da inicialização do SDK ou após o fechamento da sessão

Exemplo:

const sdk = GamanzaEngageWebClientSDK.getInstance();

ou

const { Player } = GamanzaEngageWebClientSDK.getInstance();

Métodos de Instância

closeSession(): Promise<void>

[OBRIGATÓRIO] Destrói a instância do SDK e limpa todos os recursos. Este método:

  • Limpa a sessão do usuário atual
  • Exclui todos os dados necessários para a comunicação da API
  • Fecha todas as conexões ativas
  • Destrói a instância do SDK (exigindo re-inicialização)

Chame closeSession() apenas quando o usuário sair ou a sessão expirar devido à inatividade no FE.

  • A expiração da sessão ativa do SDK é definida para 1 hora após a criação.
  • O SDK trata isso automaticamente, e as solicitações com falha serão retentadas automaticamente.
  • A sessão persiste através de recarregamentos em vez de ser invalidada e recriada toda vez.

Retorna:

  • Promise<void>: Uma promessa que é resolvida quando a sessão é fechada

Exemplo:

await sdk.closeSession();

Módulos Públicos

O SDK fornece acesso aos seguintes módulos por meio de propriedades públicas:

Events: RtmEventsModule

Funcionalidade de mensagens em tempo real e manipulação de eventos. Documentação

Player: PlayerModule

Gerenciamento de dados do jogador, incluindo informações de perfil e moeda virtual. Documentação

RewardShop: RewardShopModule

Funcionalidade da loja de recompensas para navegar e comprar recompensas. Documentação

Missions: MissionsModule

Funcionalidade de gerenciamento e acompanhamento de missões. Documentação

Tournaments: TournamentsModule

Funcionalidades de participação e gerenciamento de torneios. Documentação

RewardsProcessor: RewardsProcessorModule

Funcionalidade de processamento e resgate de recompensas. Documentação

Crm: CrmModule

Recursos de gerenciamento de relacionamento com o cliente. Documentação

FeatureFlags: FeatureFlagsModule

Gerenciamento de recursos de controle dinâmico de recursos. Documentação

Catalog: CatalogModule

Funcionalidade de navegação e gerenciamento do catálogo de jogos. Documentação

MiniGames: MiniGamesModule

Funcionalidade de gerenciamento e acompanhamento de minijogos. Documentação

Exemplo de Uso

import { GamanzaEngageWebClientSDK } from '@gamanza-engage/web-client-sdk';
// Inicializar o SDK const config = { identityToken: 'seu-token-de-identidade', serviceUrl: '[https://api.gamanzaengage.com](https://api.gamanzaengage.com)' };
try {
const sdk = await GamanzaEngageWebClientSDK.init(config);
}catch (e: SDKNotInitializedException) {}
// Usar módulos do SDK const playerData = await sdk.Player.getPlayerData(); const missions = await sdk.Missions.getActiveMissions();
// Sempre fechar a sessão quando terminar await sdk.closeSession(); } catch (error) { console.error('Falha na inicialização do SDK:', error); }

Tratamento de Erros

O SDK lança as seguintes exceções:

SDKNotInitializedException

Lançado ao tentar obter a instância do SDK antes da inicialização ou após o fechamento da sessão.

Configuração Global

O SDK suporta as seguintes opções de configuração global:

window.GMZ_ENG_DEBUG

Defina como true para habilitar o registro de depuração em todo o SDK.

window.GMZ_ENG_DEBUG = true;

Notas Importantes

  1. Padrão Singleton: O SDK usa um padrão singleton. Só pode existir uma instância por vez.

  2. Inicialização Obrigatória: Sempre chame init() antes de usar qualquer funcionalidade do SDK.

  3. Gerenciamento de Sessão: Sempre chame closeSession() quando terminar para limpar os recursos corretamente e evitar problemas com os dados da sessão do jogador.

  4. Tratamento de Erros: Implemente o tratamento adequado de erros para todas as operações assíncronas.

Definições de Tipo

O SDK exporta definições de tipo abrangentes para todas as interfaces e estruturas de dados. Importe-os junto com a classe SDK principal:

import { 
GamanzaEngageWebClientSDK,
SimpleResponse,
PaginationResponse,
// ... outros tipos
} from '@gamanza-engage/web-client-sdk'

Registro de Alterações

Conteúdo

1.15.0 (2026-02-24)

  • feat(TIP-263): Adicionar assinaturas de alteração de posição em tempo real no placar de líderes
    • Novo método: subscribeForTournamentPositionChange(tournamentId, callback, options?)
      • Ouve eventos leaderboardPositionsChanged limitados a um torneio específico
      • Retorna uma função de cancelamento de assinatura para limpeza
      • Suporta callbacks assíncronos com tratamento automático de rejeição
      • Aceita SubscriptionOptions opcionais (uma vez, filtro, tempo limite, etc.)
  • feat(MGD-200): Adicionar novas missões em tempo real de evento:on:rewardClaimed para limpar os pacotes de missões
    • Novo evento em tempo real: missions:on:rewardClaimed
      • Limpar a lista de pacotes de missões, ativos e expirados, quando uma recompensa de missão é reivindicada
  • correção de bug(leaderboardUpdated): Adicionar assinatura de evento em tempo real tournaments:on:leaderboardReady ausente

1.14.0 (2026-02-17)

  • feat(TIP-263): Adicionar assinaturas de alteração de posição em tempo real no placar de líderes
    • Novo método: subscribeForTournamentPositionChange(tournamentId, callback, options?)
      • Ouve eventos leaderboardPositionsChanged limitados a um torneio específico
      • Retorna uma função de cancelamento de assinatura para limpeza
      • Suporta callbacks assíncronos com tratamento automático de rejeição
      • Aceita SubscriptionOptions opcionais (uma vez, filtro, tempo limite, etc.)

1.12.0 (2026-02-13)

  • feat(TIP-188): Adicionar Contagem de Participantes a getLeaderboardForTournament
    • Novo método: getLeaderboardForTournamentWithParticipantCount
      • Recupere os platôs de líderes de torneios com a contagem total de participantes em uma única solicitação.

1.11.0 (2026-01-28)

  • feat(TIP-226): Adicionar notificação em tempo real de bônus concedido na recompensa

    • Processador de Recompensas: Adicionado um novo evento rewardProcessor:on:bonusGranted para notificar quando um jogador recebe uma recompensa de bônus.
    • Cliente de Socket: Registrado o novo evento no cliente de socket.
    • Documentação: Atualizada a documentação para incluir o novo evento.

1.10.0 (2026-01-23)

  • feat(TIP-215): SDK: Missões | Adicionar filtro para ignorar pacotes por tipo de recompensa

    • Módulo de Missões - Filtragem Aprimorada de Pacotes: Os seguintes métodos paginados de pacotes agora suportam a filtragem de pacotes por tipo de recompensa:

      • getPlayerBundlesActivePaginated
      • getPlayerBundlesEligiblePaginated
      • getPlayerBundlesHistoryPaginated
    • Remoção de propriedades de auditoria: Removida a propriedade endedBy do tipo PlayerBundlesExpired.


1.9.0 (2026-01-16)

  • feat(TIP-185): SDK: Missões | Implementar novas funções de paginação de pacotes de jogador

    • Módulo de Missões: Listas paginadas: Foram introduzidos três novos métodos no MissionsModule para uma recuperação mais eficiente de pacotes de missão usando paginação. Isso substitui a necessidade de carregar todos os dados de uma só vez, melhorando significativamente o desempenho para jogadores com histórico extenso.

      • getPlayerBundlesActivePaginated: Recupera pacotes ativos e em andamento.
      • getPlayerBundlesEligiblePaginated: Recupera pacotes para os quais o jogador é elegível, mas ainda não iniciou.
      • getPlayerBundlesHistoryPaginated: Recupera pacotes concluídos ou expirados com opção de filtragem por intervalo de datas UTC.
    • Segurança de tipo aprimorada: Adicionados tipos DTO específicos para respostas paginadas (PlayerBundlesActive, PlayerBundlesEligible e PlayerBundlesExpired) para fornecer estruturas de dados mais limpas, omitindo detalhes internos.

    • Atualização do Guia de Missões: A documentação missions.module.md foi atualizada para incluir os novos métodos paginados e exemplos de uso.


1.8.1 (2025-12-09)

  • bugfix(GAM-2454): SDK: Missões | Status 'abortado' ausente em MissionStatusEnum
    • Adicionado o status ABORTED ao MissionStatusEnum em missions.interface.ts

1.8.0 (2025-12-02)

  • feat(GAM-2409): Adicionar campo groupId a eventos de recompensa administrativa

    • Atualizados os eventos rewardProcessor:on:claimRewardAdmin e rewardProcessor:on:rewardCancelled para incluir o campo opcional groupId.
    • Refletidas as alterações na documentação e definições de tipo para consistência.
  • bugfix(TIP-174): Módulo de Mini Jogos ausente no arquivo Barrel

    • Adicionado MiniGamesModule ao arquivo index.ts para exportar o módulo.

1.7.0 (2025-11-07)

  • feat(GAM-2382): Processador de Recompensas Adiciona os eventos de reivindicação manual e cancelamento ao Módulo RTM

    Novos Eventos em Tempo Real

    • rewardProcessor:on:claimRewardAdmin: Novo evento acionado quando uma recompensa é reivindicada por um operador administrativo
      • Propriedades: playerId, rewardType, rewardId, source, timestamp
      • Tipo: Direto | Garantia: FIRE_FORGET
    • rewardProcessor:on:rewardCancelled: Novo evento acionado quando uma recompensa é cancelada por um operador administrativo
      • Propriedades: playerId, rewardType, rewardId, source, timestamp
      • Tipo: Direto | Garantia: FIRE_FORGET

    Assinaturas de Eventos de Socket

    • Registrados novos eventos de reivindicação e cancelamento de recompensas administrativas no cliente de socket
    • Melhoria da sincronização de cache com alterações de estado de recompensa do back-end

  • feat(PEPD-1546): Incluir propriedade groupId no evento manualRewardAwarded

    Atualizações de Estrutura de Dados de Eventos

    • Adicionado campo opcional groupId à interface ManualRewardAwardedEventData
    • Aprimorado suporte a metadados com Record<string, unknown> para dados de evento de recompensa

  • feat(GAM-2414): Evento de Torneio para Cancelamento Administrativo

    • Adicionar novo evento RTM tournaments:on:canceled para notificar quando o administrador cancela um torneio
    • Registrar ouvinte de eventos no módulo TournamentsModule para limpar o cache de torneios ativos no cancelamento
    • Atualizar a interface EventTypeMap com o tipo TournamentCanceledEventData
    • Incluir evento de cancelamento de torneio na lista de inscrição do cliente de soquete
    • Documentar o novo evento com a estrutura de payload e exemplos de uso no arquivo rtm-events.module.md

  • feat(GAM-2413): Obter informações de posição do jogador para o placar de liderança do torneio

    • Adicionada uma nova função chamada getPlayerLeaderboardsPositionInfo no módulo de torneios para retornar as informações de posição do jogador para os ids de torneio fornecidos.
    • Adicionadas documentações TSDocs detalhando a funcionalidade da função. Até cinco ids de torneio são suportados por solicitação.
    • Atualizados os documentos do SDK para adicionar documentação para desenvolvedores sobre getPlayerLeaderboardsPositionInfo

1.6.0 (2025-10-15)

  • feat(Tournaments and Missions Buy-In): Habilitar Suporte para Buy-In de Torneios e Missões

    Aprimorado os módulos TournamentsModule e MissionsModule com suporte abrangente de entrada opcional e compra:

    Alterações de Interface Principal (commons.interface.ts)

    • Adicionado o enum BuyInOptions para definir os tipos de entrada:
      • TOKENS: Taxa de inscrição baseada em tokens
      • FREE: Sem custo de inscrição
    • Configuração centralizada de compra para reutilização em torneios e missões

    Alterações de Interface de Torneio (tournaments.interface.ts)

    • Estendida a interface TournamentType com novos campos:
      • isPlayerOptIn: flag booleana indicando se o jogador participou opcionalmente do torneio
      • buyIn: Configuração do tipo de entrada usando o enum BuyInOptions
      • buyOptions: Detalhes opcionais da transação para custos de inscrição em torneios (tokens/moeda)
    • Melhorada a documentação JSDoc para optIn, buyIn e buyOptions com exemplos detalhados de uso
    • Atualizada a documentação de campo com exemplos e casos de uso abrangentes de segurança de tipo
    • Melhorada a documentação para os campos winTxId e type com descrições esclarecidas

    Implementação do Módulo de Torneio (tournaments.module.ts)

    • Implementado o método playerOptInTournament() para registro manual de torneios
    • Suporta torneios com entrada gratuita e baseada em tokens
    • Valida o saldo do jogador para inscrições baseadas em tokens
    • Retorna HTTP 402 (Pagamento Necessário) para fundos insuficientes
    • Invalida automaticamente todos os caches relacionados a torneios após a adesão bem-sucedida
    • Inclui JSDoc abrangente com padrões de tratamento de erros e exemplos de uso

    Mudanças na Interface de Missão (missions.interface.ts)

    • Interface MissionHistoryBundleDetailsType estendida com novos campos:
      • buyIn: Configuração de tipo de entrada opcional usando o enum BuyInOptions
      • buyOptions: Detalhes de transação opcionais para custos de entrada do pacote de missão (fichas/moeda)
    • Adicionada documentação JSDoc abrangente com:
      • Padrões de entrada baseados em fichas e em dinheiro
      • Exemplos de validação de saldo
      • Padrões de renderização da interface para exibições de compra de entrada
      • Guardas de tipo para manipulação segura de tipos de entrada

    Implementação do Módulo de Missão

    • Aprimorado playerRequestOptInMissionBundle() para suportar validação de compra de entrada
    • Suporta entradas de pacote de missão gratuitas e baseadas em fichas
    • Valida o saldo do jogador para entradas de pacote de missão baseadas em fichas
    • Retorna códigos de erro apropriados para fundos insuficientes
    • Invalida automaticamente os caches relacionados a missões após a adesão bem-sucedida

  • feat(Multiplicador de Vitórias em Torneios): Multiplicador de vitórias em torneios adicionado aos dados do evento de torneio

ALTERAÇÕES IMPORTANTES (Condicional apenas se estiver em uso):

  • Removido o TournamentTypeEnum.BONUS_BUY (ainda não suportado)
  • Estruturas de dados de eventos de torneio atualizadas com digitação mais rigorosa

Adicionado:

  • Tipo de união discriminado RoundInfo para manipulação segura de tipos de dados de rodada
    • Discrimina automaticamente entre os tipos de indústria CASINO e SPORT
    • Rodadas de CASINO incluem a propriedade game obrigatória (GameInfoStruct)
    • Rodadas de SPORT incluem a propriedade sports obrigatória (SportInfoStruct[])
    • Evita o acesso a propriedades inválidas no momento da compilação
  • Tipo RoundInfoBase contendo propriedades de rodada compartilhadas
  • Interface RoundIndustryPropertiesMap para mapear tipos de indústria para propriedades
  • Tipo GameInfoStruct (gameId, gameName)
  • Tipo SportInfoStruct (eventName, matchDate, sportName?)
  • Documentação JSDoc abrangente para campos relacionados a rodadas

LeaderboardPlayerType aprimorado:

  • Adicionado campo type (TournamentTypeEnum) para identificar o tipo de torneio
  • Adicionado campo opcional round (RoundInfo) para torneios de maior vitória
  • Adicionado JSDoc explicando quando os dados da rodada estão disponíveis/indefinidos
  • Condições de disponibilidade de spinsLeft documentadas

PlayerLeaderboardUpdatedEventData aprimorado:

  • Adicionado o campo type às entradas de torneio
  • Adicionado o campo opcional round às entradas de torneio
  • Adicionada documentação JSDoc detalhada sobre as condições de disponibilidade do campo round

Melhorado o TournamentsUpdatedEventData:

  • Refatorada a definição de tipo de leaderboard para maior clareza
  • Tipo de interseção simplificado com o utilitário Omit type

Documentação Atualizada:

  • Melhorada a rtm-events.module.md com informações de tipo precisas
  • Substituídos os tipos genéricos any por tipos TypeScript específicos
  • Adicionadas anotações de tipo apropriadas para todas as propriedades de eventos de torneio
  • Melhorada a clareza do tipo para assinaturas de eventos de torneio

Detalhes Técnicos:

  • Aproveita os tipos mapeados do TypeScript para geração automática de união discriminada
  • Mantém a segurança de tipo através da inclusão condicional de propriedade
  • Dados de round devidamente tipados com base no tipo de indústria de torneio
  • Versão incrementada para 1.6.0

Esta implementação garante a segurança de tipo em tempo de compilação ao trabalhar com dados de round de torneio, evitando erros em tempo de execução ao acessar propriedades que não existem para um determinado tipo de indústria de torneio.

1.5.0 (2025-10-02)

  • feat(Adicionar no Opt In de Missões): Missões Adicionadas novas propriedades para verificar os requisitos de opt-in.

    • Inclui duas novas propriedades na interface MissionHistoryBundleDetailsType e na resposta da API para incluir
      • playerRequiresOptIn: Determinar se o pacote de missão requer opt-in do jogador para iniciar o recurso.
      • playerHasOptedIn: Determinar se o jogador realizou a ação de opt-in.
    • Atualizada a função getPlayerBundlesActive no módulo Missões para permitir que os desenvolvedores definam o Cache TLL em segundos como um argumento opcional. Zero significa que nenhum cache é aplicado.

1.4.0 (2025-09-23)

  • feat(Elegibilidade e Visibilidade de Produtos): Determina quais jogadores podem comprar o Produto da Loja de Recompensas

    • Adicionar interfaces EligibilityMap e VisibilityMap abrangentes com uniões discriminadas
    • Implementar propriedade productEligibility de tipo seguro na interface ProductType
    • Introduzir a interface VisibilityOptions com recursos de filtragem por país/classificação
    • Melhorar a segurança de tipo do TypeScript através de tipos de união e discriminação adequada
    • Otimizar o gerenciamento de cache, removendo o armazenamento em cache de produtos redundantes em getAllProducts()
    • Reduzir o TTL do cache de produtos individuais de 30 minutos para 15 minutos
    • Atualizar a documentação abrangente com descrições detalhadas de interfaces e exemplos de uso
    • Adicionar comentários JSDoc explicando as regras de elegibilidade, opções de visibilidade e configurações de filtro
    • Incluir exemplos de código práticos para verificação de tipo de elegibilidade e tratamento de erros

1.3.0 (2025-09-17)

  • feat(GAM-2322): Integrar Evento On Manual Reward Awarded
    • Adicionado um novo evento RTM chamado ON_MANUAL_REWARD_AWARDED para notificar o jogador quando uma recompensa manual for concedida.
    • Atualizou a documentação do SDK para incluir esse novo detalhe do evento.

1.2.0 (2025-08-14)

  • recurso (TIP-94): Adicionar opção de opt-in/opt-out no SDK

    Adicionadas duas novas funções ao módulo de Missões para permitir que os jogadores façam opt-in ou opt-out de um pacote de missões:

    • playerRequestOptInMissionBundle
    • playerRequestOptOutMissionBundle
    • Atualizar documentação do módulo de missões

  • recurso (TIP-93): Adicionar uma opção de rejeitar recompensas no SDK

    • Adicionar playerRequestDeclineReward() método para rejeição individual de recompensas
    • Adicionar playerRequestDeclineMissionRewards() método para rejeição em massa de recompensas de missão
    • Adicionar playerRequestDeclineRewardByGroupId() método para rejeição em massa de recompensas do jogador
    • Implementar invalidação de cache adequada nas alterações de status da recompensa
    • Adicionar tratamento abrangente de erros e validação de resposta
    • Atualizar os endpoints da API para suportar novas operações de rejeição

1.1.0 (2025-08-11)

  • recurso (GAM-2272): Incluir eventos de término de missão e pacote

    Atualizados os eventos RTM para incluir os seguintes eventos:

    • ON_MISSION_ENDED: Evento acionado quando uma missão é encerrada manualmente por um operador do painel administrativo.
    • ON_MISSION_BUNDLE_ENDED: Evento acionado quando um pacote é encerrado manualmente por um operador do painel administrativo.

    Atualizou a documentação do SDK para incluir esses novos detalhes de eventos.


📢 Este SDK é proprietário. O uso é regido pelo Contrato de Licença do SDK Gamanza Engage. A redistribuição ou modificação é estritamente proibida.