Pular para o conteúdo principal
Gamanza Engages

Gamanza Engage Web Client SDK

Resumen

El Gamanza Engage Web Client SDK permite a los desarrolladores crear interfaces de usuario ricas y personalizables que se integran sin problemas con la plataforma Gamanza Engage. Diseñado para la flexibilidad y el rendimiento, este SDK proporciona una interfaz estructurada y modular para interactuar con funciones clave de participación, como perfiles de jugadores, misiones, torneos, recompensas y más.

Al aprovechar este SDK, puedes:

  • Acceder a datos y eventos en tiempo real del jugador autenticado.
  • Escuchar actualizaciones en vivo de la plataforma de participación del jugador de Gamanza.
  • Construir componentes de lealtad y gamificación personalizados adaptados a las necesidades de tu producto.
  • Mantener una integración limpia y consistente utilizando una arquitectura basada en un único punto de acceso.

Ya sea que estés construyendo desde cero o mejorando un frontend existente, el SDK simplifica la comunicación con la API frontend de Gamanza Engage, ayudándote a ofrecer experiencias atractivas con facilidad y eficiencia.

Inicio rápido

Antes de empezar

  1. Comprender las API que necesitas implementar
  2. Crear un ID de cliente
  3. Configurar la autenticación

Instalar el SDK

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

Uso del SDK

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

export const initSDK = async () => {
await GamanzaEngageWebClientSDK.init({
clientId: 'your client id',
identityToken: 'player identity token',
serviceUrl: '[https://fontend-api-[your-instance].gamanzaengage.com]'
});

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

Métodos estáticos

init(config: AuthConfig): Promise<GamanzaEngageWebClientSDK>

Inicializa el SDK con la configuración de autenticación proporcionada. Este método debe llamarse antes de usar cualquier funcionalidad del SDK.

Parámetros:

  • config (AuthConfig): Objeto de configuración de autenticación que contiene:
    • clientId (string): ID de cliente generado en tu instancia de administración de Gamanza Engage
    • identityToken (string): El token de identidad para la autenticación
    • serviceUrl (string): La URL base para el servicio Gamanza Engage

Retorna:

  • Promise<GamanzaEngageWebClientSDK>: Una promesa que se resuelve en la instancia del SDK inicializada

Ejemplo:

const config = {
clientId: 'your-client-id',
identityToken: 'your-identity-token',
serviceUrl: '[https://fontend-api-[your-instance].gamanzaengage.com]'
};
const sdk = await GamanzaEngageWebClientSDK.init(config);

getInstance(): GamanzaEngageWebClientSDK

Devuelve la instancia singleton del SDK. El SDK debe inicializarse usando init() antes de llamar a este método.

Devuelve:

  • GamanzaEngageWebClientSDK: La instancia singleton del SDK

Lanza:

  • SDKNotInitializedException: Cuando se llama antes de la inicialización del SDK o después del cierre de la sesión

Ejemplo:

const sdk = GamanzaEngageWebClientSDK.getInstance();

o

const { Player } = GamanzaEngageWebClientSDK.getInstance();

Métodos de instancia

closeSession(): Promise<void>

[OBLIGATORIO] Destruye la instancia del SDK y limpia todos los recursos. Este método:

  • Borra la sesión de usuario actual
  • Elimina todos los datos necesarios para la comunicación de la API
  • Cierra todas las conexiones activas
  • Destruye la instancia del SDK (requiere reinicialización)

Llama a closeSession() solo cuando el usuario cierra la sesión o esta expira por inactividad en el FE.

  • La expiración de la sesión activa del SDK se establece en 1 hora después de su creación.
  • El SDK maneja esto automáticamente, y las solicitudes fallidas se volverán a intentar automáticamente.
  • La sesión persiste a través de las recargas en lugar de invalidarse y recrearse cada vez.

Devuelve:

  • Promise<void>: Una promesa que se resuelve cuando se cierra la sesión

Ejemplo:

await sdk.closeSession();

Módulos públicos

El SDK proporciona acceso a los siguientes módulos a través de propiedades públicas:

Events: RtmEventsModule

Funcionalidad de mensajería en tiempo real y manejo de eventos. Documentación

Player: PlayerModule

Gestión de datos del jugador, incluida la información del perfil y la moneda virtual. Documentación

RewardShop: RewardShopModule

Funcionalidad de la tienda de recompensas para navegar y comprar recompensas. Documentación

Missions: MissionsModule

Funcionalidad de gestión y seguimiento de misiones. Documentación

Tournaments: TournamentsModule

Funciones de participación y gestión de torneos. Documentación

RewardsProcessor: RewardsProcessorModule

Funcionalidad de procesamiento y canje de recompensas. Documentación

Crm: CrmModule

Características de gestión de relaciones con los clientes. Documentación

FeatureFlags: FeatureFlagsModule

Gestión de banderas de funcionalidad para el control dinámico de funciones. Documentación

Catalog: CatalogModule

Funcionalidad de navegación y gestión del catálogo de juegos. Documentación

MiniGames: MiniGamesModule

Funcionalidad de gestión y seguimiento de minijuegos. Documentación

Ejemplo de uso

import { GamanzaEngageWebClientSDK } from '@gamanza-engage/web-client-sdk';
// Inicializar el SDK const config = { identityToken: 'your-identity-token', serviceUrl: '[https://api.gamanzaengage.com](https://api.gamanzaengage.com)' };
try {
const sdk = await GamanzaEngageWebClientSDK.init(config);
}catch (e: SDKNotInitializedException) {}
// Usar módulos del SDK const playerData = await sdk.Player.getPlayerData(); const missions = await sdk.Missions.getActiveMissions();
// Siempre cerrar la sesión cuando se termine await sdk.closeSession(); } catch (error) { console.error('Falló la inicialización del SDK:', error); }

Manejo de errores

El SDK lanza las siguientes excepciones:

SDKNotInitializedException

Se lanza al intentar obtener la instancia del SDK antes de la inicialización o después del cierre de la sesión.

Configuración global

El SDK admite las siguientes opciones de configuración global:

window.GMZ_ENG_DEBUG

Establézcalo en true para habilitar el registro de depuración en todo el SDK.

window.GMZ_ENG_DEBUG = true;

Notas importantes

  1. Patrón Singleton: El SDK utiliza un patrón singleton. Solo puede existir una instancia a la vez.

  2. Inicialización requerida: Llame siempre a init() antes de usar cualquier funcionalidad del SDK.

  3. Gestión de sesiones: Llame siempre a closeSession() cuando haya terminado para limpiar adecuadamente los recursos y evitar problemas con los datos de la sesión del jugador.

  4. Manejo de errores: Implementar un manejo de errores adecuado para todas las operaciones asincrónicas.

Definiciones de tipos

El SDK exporta definiciones de tipos completas para todas las interfaces y estructuras de datos. Impórtalos junto con la clase principal del SDK:

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

Registro de cambios

Details
Contenido

1.15.0 (2026-02-24)

  • feat(TIP-263): Agregar suscripciones de cambio de posición en tiempo real en el tablero de clasificación
    • Nuevo método: subscribeForTournamentPositionChange(tournamentId, callback, options?)
      • Escucha eventos leaderboardPositionsChanged con alcance a un torneo específico
      • Devuelve una función de cancelación de suscripción para la limpieza
      • Admite devoluciones de llamada asincrónicas con manejo automático de rechazo
      • Acepta SubscriptionOptions opcionales (una vez, filtro, tiempo de espera, etc.)
  • feat(MGD-200): Agregar nuevas misiones en tiempo real: on:rewardClaimed para limpiar los paquetes de misiones
    • Nuevo evento en tiempo real: missions:on:rewardClaimed
      • Limpiar la lista de paquetes de misiones, activos y caducados, cuando se reclama una recompensa de misión
  • corrección de errores(leaderboardUpdated): Agregar la suscripción faltante de eventos en tiempo real tournaments:on:leaderboardReady

1.14.0 (2026-02-17)

  • feat(TIP-263): Agregar suscripciones de cambio de posición en tiempo real en el tablero de clasificación
    • Nuevo método: subscribeForTournamentPositionChange(tournamentId, callback, options?)
      • Escucha eventos leaderboardPositionsChanged con alcance a un torneo específico
      • Devuelve una función de cancelación de suscripción para la limpieza
      • Admite devoluciones de llamada asincrónicas con manejo automático de rechazo
      • Acepta SubscriptionOptions opcionales (una vez, filtro, tiempo de espera, etc.)

1.12.0 (2026-02-13)

  • feat(TIP-188): Agregar recuento de participantes a getLeaderboardForTournament
    • Nuevo método: getLeaderboardForTournamentWithParticipantCount
      • Recuperar los tableros de clasificación de los torneos con el recuento total de participantes en una sola solicitud.

1.11.0 (2026-01-28)

  • feat(TIP-226): Agregar notificación en tiempo real para bonificación de recompensa otorgada

    • Rewards Processor: Se agregó un nuevo evento rewardProcessor:on:bonusGranted para notificar cuando un jugador recibe una recompensa de bonificación.
    • Socket Client: Se registró el nuevo evento en el cliente de socket.
    • Documentation: Se actualizó la documentación para incluir el nuevo evento.

1.10.0 (2026-01-23)

  • feat(TIP-215): SDK: Misiones | Agregar filtro para ignorar paquetes por tipo de recompensa

    • Misiones Módulo - Mejora del Filtrado de Paquetes: Los siguientes métodos paginados de paquetes ahora admiten el filtrado de paquetes por tipo de recompensa:

      • getPlayerBundlesActivePaginated
      • getPlayerBundlesEligiblePaginated
      • getPlayerBundlesHistoryPaginated
    • Eliminados los props de auditoría: Se eliminó la propiedad endedBy del tipo PlayerBundlesExpired.


1.9.0 (2026-01-16)

  • feat(TIP-185): SDK: Misiones | Implementar nuevas funciones de páginas de lotes de jugadores

    • Módulo de Misiones: Listas paginadas: Se introdujeron tres nuevos métodos al MissionsModule para una recuperación más eficiente de los lotes de misiones utilizando la paginación. Esto reemplaza la necesidad de cargar todos los datos de una vez, mejorando significativamente el rendimiento para los jugadores con un historial extenso.

      • getPlayerBundlesActivePaginated: Recupera los lotes activos y en curso.
      • getPlayerBundlesEligiblePaginated: Recupera los lotes para los que el jugador es elegible pero no ha iniciado.
      • getPlayerBundlesHistoryPaginated: Recupera los lotes completados o vencidos con un filtro de rango de fechas UTC opcional.
    • Seguridad de tipo mejorada: Se agregaron tipos DTO específicos para las respuestas paginadas (PlayerBundlesActive, PlayerBundlesEligible y PlayerBundlesExpired) para proporcionar estructuras de datos más limpias al omitir detalles solo internos.

    • Actualización de la guía de misiones: Se actualizó la documentación missions.module.md para incluir los nuevos métodos paginados y sus ejemplos de uso.


1.8.1 (2025-12-09)

  • corrección de errores(GAM-2454): SDK: Misiones | Falta el estado anulado en MissionStatusEnum
    • Se agregó el estado ABORTED a MissionStatusEnum en missions.interface.ts

1.8.0 (2025-12-02)

  • feat(GAM-2409): Agregar el campo groupId a los eventos de recompensa de administrador

    • Se actualizaron los eventos rewardProcessor:on:claimRewardAdmin y rewardProcessor:on:rewardCancelled para incluir el campo opcional groupId.
    • Se reflejaron los cambios en la documentación y las definiciones de tipos para mantener la coherencia.
  • corrección de errores(TIP-174): Falta el módulo de minijuegos en el archivo Barrel

    • Se agregó MiniGamesModule al archivo index.ts para exportar el módulo.

1.7.0 (2025-11-07)

  • feat(GAM-2382): El procesador de recompensas agrega los eventos de reclamación manual y cancelación al módulo RTM

    Nuevos eventos en tiempo real

    • rewardProcessor:on:claimRewardAdmin: Nuevo evento que se activa cuando un operador de administración reclama una recompensa
      • Propiedades: playerId, rewardType, rewardId, source, timestamp
      • Tipo: Directo | Garantía: FIRE_FORGET
    • rewardProcessor:on:rewardCancelled: Nuevo evento que se activa cuando un operador de administración cancela una recompensa
      • Propiedades: playerId, rewardType, rewardId, source, timestamp
      • Tipo: Directo | Garantía: FIRE_FORGET

    Suscripciones a eventos de socket

    • Se registraron nuevos eventos de reclamación y cancelación de recompensas de administración en el cliente de socket
    • Mejorada la sincronización de la caché con los cambios de estado de recompensa en el backend

  • feat(PEPD-1546): Incluir la propiedad groupId en el evento manualRewardAwarded

    Actualizaciones de la estructura de datos del evento

    • Se agregó el campo opcional groupId a la interfaz ManualRewardAwardedEventData
    • Mejorada la compatibilidad con metadatos con Record<string, unknown> para los datos del evento de recompensa

  • feat(GAM-2414): Evento de Torneo para Cancelación Administrativa

    • Agregar un nuevo evento RTM tournaments:on:canceled para notificar cuando un administrador cancela un torneo
    • Registrar un escuchador de eventos en TournamentsModule para limpiar la caché de torneos activos al cancelarse
    • Actualizar la interfaz EventTypeMap con el tipo TournamentCanceledEventData
    • Incluir el evento de cancelación de torneos en la lista de suscripción del cliente de socket
    • Documentar el nuevo evento con la estructura del payload y ejemplos de uso en rtm-events.module.md

  • feat(GAM-2413): Obtener información de posiciones de jugadores para el podio del torneo

    • Se agregó una nueva función llamada getPlayerLeaderboardsPositionInfo en el módulo de torneos para devolver la información de posición del jugador para los ids de torneos dados.
    • Se agregaron TSDocs que detallan la funcionalidad de la función. Se admiten hasta cinco ids de torneo por solicitud.
    • Actualizada la documentación del SDK para agregar documentación para desarrolladores de getPlayerLeaderboardsPositionInfo

1.6.0 (2025-10-15)

  • feat(Torneos y Misiones Buy-In): Habilitar soporte de Buy-In para Torneos y Misiones

    Mejorados los módulos TournamentsModule y MissionsModule con un soporte integral de opciones y buy-in:

    Cambios en la interfaz principal (commons.interface.ts)

    • Agregado el enum BuyInOptions para definir los tipos de entrada:
      • TOKENS: Tarifa de entrada basada en tokens
      • FREE: Sin costo de entrada
    • Configuración de buy-in centralizada para su reutilización en torneos y misiones

    Cambios en la interfaz de Torneos (tournaments.interface.ts)

    • Ampliada la interfaz TournamentType con nuevos campos:
      • isPlayerOptIn: bandera booleana que indica si el jugador se ha registrado en el torneo
      • buyIn: Configuración del tipo de entrada usando el enum BuyInOptions
      • buyOptions: Detalles de transacción opcionales para los costos de entrada al torneo (tokens/moneda)
    • Mejorada la documentación JSDoc para optIn, buyIn y buyOptions con ejemplos de uso detallados
    • Actualizada la documentación de los campos con ejemplos de seguridad de tipos y casos de uso exhaustivos
    • Mejorada la documentación para los campos winTxId y type con descripciones aclaradas

    Implementación del módulo de torneos (tournaments.module.ts)

    • Implementado el método playerOptInTournament() para el registro manual de torneos
    • Admite torneos con buy-in gratuito y basado en tokens
    • Valida el saldo del jugador para las entradas basadas en tokens
    • Devuelve el código de estado HTTP 402 (Pago requerido) por fondos insuficientes
    • Invalida automáticamente todas las memorias caché relacionadas con el torneo después de una inscripción exitosa
    • Incluye JSDoc completo con patrones de manejo de errores y ejemplos de uso

    Cambios en la interfaz de misión (missions.interface.ts)

    • Interfaz MissionHistoryBundleDetailsType ampliada con nuevos campos:
      • buyIn: Configuración de tipo de entrada opcional utilizando el enum BuyInOptions
      • buyOptions: Detalles de transacción opcionales para los costos de entrada del paquete de misiones (tokens/moneda)
    • Documentación JSDoc integral agregada con:
      • Patrones de entrada basados en tokens y en efectivo
      • Ejemplos de validación de saldo
      • Patrones de representación de la interfaz de usuario para pantallas de inscripción
      • Guardias de tipo para un manejo seguro de la inscripción

    Implementación del módulo de misión

    • Se mejoró playerRequestOptInMissionBundle() para admitir la validación de la inscripción
    • Admite entradas de paquete de misiones gratuitas y basadas en tokens
    • Valida el saldo del jugador para las entradas de paquete de misiones basadas en tokens
    • Devuelve los códigos de error apropiados para fondos insuficientes
    • Invalida automáticamente las memorias caché relacionadas con las misiones después de una inscripción exitosa

  • feat(Multiplicador de ganancia de torneos): Se agregó el multiplicador de ganancia de torneos a los datos del evento del torneo

CAMBIOS IMPORTANTES (Condicional solo si se está utilizando):

  • Se eliminó TournamentTypeEnum.BONUS_BUY (aún no admitido)
  • Se actualizaron las estructuras de datos del evento del torneo con un tipado más estricto

Agregado:

  • Tipo de unión discriminado RoundInfo para un manejo seguro de los datos de la ronda
    • Discrimina automáticamente entre los tipos de industria CASINO y SPORT
    • Las rondas de CASINO incluyen la propiedad game requerida (GameInfoStruct)
    • Las rondas de SPORT incluyen la propiedad sports requerida (SportInfoStruct[])
    • Evita el acceso a propiedades no válidas en tiempo de compilación
  • Tipo RoundInfoBase que contiene las propiedades de ronda compartidas
  • Interfaz RoundIndustryPropertiesMap para asignar tipos de industria a propiedades
  • Tipo GameInfoStruct (gameId, gameName)
  • Tipo SportInfoStruct (eventName, matchDate, sportName?)
  • Documentación JSDoc integral para los campos relacionados con la ronda

LeaderboardPlayerType mejorado:

  • Se agregó el campo type (TournamentTypeEnum) para identificar el tipo de torneo
  • Se agregó el campo opcional round (RoundInfo) para los torneos de máxima ganancia
  • Se agregó JSDoc explicando cuándo los datos de la ronda están disponibles/indefinidos
  • Se documentaron las condiciones de disponibilidad de spinsLeft

PlayerLeaderboardUpdatedEventData mejorado:

  • Se agregó el campo type a las entradas de torneos
  • Se agregó el campo opcional round a las entradas de torneos
  • Se agregó documentación JSDoc detallada sobre las condiciones de disponibilidad del campo round

Mejorado TournamentsUpdatedEventData:

  • Refactorizada la definición de tipo de tabla de clasificación para mayor claridad
  • Simplificado el tipo de intersección con el tipo de utilidad Omit

Documentación actualizada:

  • Mejorada rtm-events.module.md con información de tipo precisa
  • Reemplazados los tipos genéricos any por tipos TypeScript específicos
  • Agregadas anotaciones de tipo apropiadas para todas las propiedades de eventos de torneo
  • Mejorada la claridad de tipo para las suscripciones a eventos de torneo

Detalles técnicos:

  • Se basa en tipos asignados de TypeScript para la generación automática de uniones discriminadas
  • Mantiene la seguridad de tipo a través de la inclusión condicional de propiedades
  • Los datos de ronda correctamente tipados según el tipo de industria del torneo
  • Versión aumentada a 1.6.0

Esta implementación garantiza la seguridad de tipo en tiempo de compilación al trabajar con datos de ronda de torneo, evitando errores de tiempo de ejecución al acceder a propiedades que no existen para un tipo de industria de torneo dado.

1.5.0 (2025-10-02)

  • feat(Misiones Complemento de Activación): Misiones Nuevas propiedades agregadas para verificar los requisitos de activación.

    • Incluye dos nuevas propiedades en la interfaz MissionHistoryBundleDetailsType y en la respuesta de la API para incluir
      • playerRequiresOptIn: Determina si el paquete de misión requiere la activación por parte del jugador para iniciar el mecanismo.
      • playerHasOptedIn: Determina si el jugador realizó la acción de activación.
    • Actualizada la función getPlayerBundlesActive en el módulo de Misiones para permitir que los desarrolladores definan el TTL de caché en segundos como un argumento opcional. Cero significa que no se aplica caché.

1.4.0 (2025-09-23)

  • feat(Elegibilidad y Visibilidad de Productos): Determina qué jugadores pueden comprar el Producto de la Tienda de Recompensas

    • Agregar interfaces EligibilityMap y VisibilityMap completas con uniones discriminadas
    • Implementar la propiedad productEligibility de tipo seguro en la interfaz ProductType
    • Introducir la interfaz VisibilityOptions con capacidades de filtrado por país/rango
    • Mejorar la seguridad de tipo de TypeScript a través de tipos de unión y una adecuada discriminación
    • Optimizar la gestión de caché eliminando el almacenamiento en caché redundante de productos en getAllProducts()
    • Reducir el TTL de caché individual de productos de 30 minutos a 15 minutos
    • Actualizar la documentación completa con descripciones detalladas de las interfaces y ejemplos de uso
    • Agregar comentarios JSDoc que expliquen las reglas de elegibilidad, las opciones de visibilidad y las configuraciones de filtro
    • Incluir ejemplos de código prácticos para la comprobación de tipos de elegibilidad y el manejo de errores

1.3.0 (2025-09-17)

  • feat(GAM-2322): Integrar Evento de Recompensa Manual Otorgada
    • Se agregó un nuevo evento RTM llamado ON_MANUAL_REWARD_AWARDED para notificar al jugador cuando se otorga una recompensa manual.
    • Se actualizaron los documentos del SDK para incluir este nuevo detalle de evento.

1.2.0 (2025-08-14)

  • feat(TIP-94): Agregar opción de activación/desactivación en el SDK

    Se agregaron dos nuevas funciones al módulo de Misiones para permitir que los jugadores se suscriban o se den de baja de un paquete de Misiones:

    • playerRequestOptInMissionBundle
    • playerRequestOptOutMissionBundle
    • Actualizar documentación del módulo de misiones

  • feat(TIP-93): Agregar una opción de rechazo para recompensas en el SDK

    • Agregar el método playerRequestDeclineReward() para el rechazo individual de recompensas
    • Agregar el método playerRequestDeclineMissionRewards() para el rechazo masivo de recompensas de misión
    • Agregar el método playerRequestDeclineRewardByGroupId() para el rechazo masivo de recompensas del jugador
    • Implementar la invalidación adecuada de la caché en los cambios de estado de la recompensa
    • Agregar un manejo de errores y validación de respuesta integral
    • Actualizar los puntos finales de la API para admitir nuevas operaciones de rechazo

1.1.0 (2025-08-11)

  • feat(GAM-2272): Incluir eventos de finalización de misión y paquete

    Se actualizaron los eventos de RTM para incluir los siguientes eventos:

    • ON_MISSION_ENDED: Evento activado cuando un operador del panel de administración finaliza manualmente una misión.
    • ON_MISSION_BUNDLE_ENDED: Evento activado cuando un operador del panel de administración finaliza manualmente un paquete.

    Se actualizaron los documentos del SDK para incluir los detalles de estos nuevos eventos.


📢 Este SDK es de propiedad exclusiva. El uso se rige por el Acuerdo de Licencia del SDK de Gamanza Engage. Se prohíbe estrictamente la redistribución o modificación.