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
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 EngageidentityToken(string): O token de identidade para autenticaçãoserviceUrl(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
-
Padrão Singleton: O SDK usa um padrão singleton. Só pode existir uma instância por vez.
-
Inicialização Obrigatória: Sempre chame
init()antes de usar qualquer funcionalidade do SDK. -
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. -
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
leaderboardPositionsChangedlimitados 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
SubscriptionOptionsopcionais (uma vez, filtro, tempo limite, etc.)
- Ouve eventos
- Novo método:
- 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
- Novo evento em tempo real:
- 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
leaderboardPositionsChangedlimitados 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
SubscriptionOptionsopcionais (uma vez, filtro, tempo limite, etc.)
- Ouve eventos
- Novo método:
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.
- Novo método:
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:bonusGrantedpara 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.
- Processador de Recompensas: Adicionado um 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:
getPlayerBundlesActivePaginatedgetPlayerBundlesEligiblePaginatedgetPlayerBundlesHistoryPaginated
-
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
ABORTEDaoMissionStatusEnumemmissions.interface.ts
- Adicionado o status
1.8.0 (2025-12-02)
-
feat(GAM-2409): Adicionar campo groupId a eventos de recompensa administrativa
- Atualizados os eventos
rewardProcessor:on:claimRewardAdminerewardProcessor:on:rewardCancelledpara incluir o campo opcionalgroupId. - Refletidas as alterações na documentação e definições de tipo para consistência.
- Atualizados os eventos
-
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
manualRewardAwardedAtualizações de Estrutura de Dados de Eventos
- Adicionado campo opcional
groupIdà interfaceManualRewardAwardedEventData - Aprimorado suporte a metadados com
Record<string, unknown>para dados de evento de recompensa
- Adicionado campo opcional
-
feat(GAM-2414): Evento de Torneio para Cancelamento Administrativo
- Adicionar novo evento RTM
tournaments:on:canceledpara 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
- Adicionar novo evento RTM
-
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
getPlayerLeaderboardsPositionInfono 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
- Adicionada uma nova função chamada
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
BuyInOptionspara definir os tipos de entrada:TOKENS: Taxa de inscrição baseada em tokensFREE: 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
TournamentTypecom novos campos:isPlayerOptIn: flag booleana indicando se o jogador participou opcionalmente do torneiobuyIn: Configuração do tipo de entrada usando o enumBuyInOptionsbuyOptions: Detalhes opcionais da transação para custos de inscrição em torneios (tokens/moeda)
- Melhorada a documentação JSDoc para
optIn,buyInebuyOptionscom 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
winTxIdetypecom 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
MissionHistoryBundleDetailsTypeestendida com novos campos:buyIn: Configuração de tipo de entrada opcional usando o enumBuyInOptionsbuyOptions: 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
- Adicionado o enum
- 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
gameobrigatória (GameInfoStruct) - Rodadas de SPORT incluem a propriedade
sportsobrigató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
anypor 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
MissionHistoryBundleDetailsTypee na resposta da API para incluirplayerRequiresOptIn: 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
getPlayerBundlesActiveno 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.
- Inclui duas novas propriedades na interface
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
- Adicionar
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.