Gamanza Engage Web Client SDK

Overview

The Gamanza Engage Web Client SDK empowers developers to build rich, customizable user interfaces that integrate seamlessly with the Gamanza Engage Platform. Designed for flexibility and performance, this SDK provides a structured, modular interface for interacting with key engagement features such as player profiles, missions, tournaments, rewards, and more.

By leveraging this SDK, you can:

Access real-time data and events for the authenticated player.
Listen for live updates from the Gamanza Player Engagement Platform.
Build custom loyalty and gamification components tailored to your product’s needs.
Maintain a clean and consistent integration using a singleton-based architecture.

Whether you're building from scratch or enhancing an existing frontend, the SDK simplifies communication with the Gamanza Engage Frontend API, helping you deliver engaging experiences with ease and efficiency.

Quickstart

Before you begin

Install the SDK

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

Using the 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);
}

Static Methods

`init(config: AuthConfig): Promise<GamanzaEngageWebClientSDK>`

Initializes the SDK with the provided authentication configuration. This method must be called before using any SDK functionality.

Parameters:

config (AuthConfig): Authentication configuration object containing:
- clientId (string): Client ID generated in your Gamanza Engage Admin Instance
- identityToken (string): The identity token for authentication
- serviceUrl (string): The base URL for the Gamanza Engage service

Returns:

Promise<GamanzaEngageWebClientSDK>: A promise that resolves to the initialized SDK instance

Example:

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`

Returns the singleton instance of the SDK. The SDK must be initialized using init() before calling this method.

Returns:

GamanzaEngageWebClientSDK: The singleton SDK instance

Throws:

SDKNotInitializedException: When called before SDK initialization or after session closure

Example:

const sdk = GamanzaEngageWebClientSDK.getInstance();

const { Player } = GamanzaEngageWebClientSDK.getInstance();

Instance Methods

`closeSession(): Promise<void>`

[MANDATORY] Destroys the SDK instance and cleans up all resources. This method:

Clears the current user session
Deletes all data required for API communication
Closes all active connections
Destroys the SDK instance (requiring re-initialization)

Returns:

Promise<void>: A promise that resolves when the session is closed

Example:

await sdk.closeSession();

Public Modules

The SDK provides access to the following modules through public properties:

`Events: RtmEventsModule`

Real-time messaging and event handling functionality. Documentation

`Player: PlayerModule`

Player data management, including profile information and virtual currency. Documentation

`RewardShop: RewardShopModule`

Reward shop functionality for browsing and purchasing rewards. Documentation

`Missions: MissionsModule`

Mission management and tracking functionality. Documentation

`Tournaments: TournamentsModule`

Tournament participation and management features. Documentation

`RewardsProcessor: RewardsProcessorModule`

Reward processing and redemption functionality. Documentation

`Crm: CrmModule`

Customer relationship management features. Documentation

`FeatureFlags: FeatureFlagsModule`

Feature flag management for dynamic feature control. Documentation

`Catalog: CatalogModule`

Game catalog browsing and management functionality. Documentation

`MiniGames: MiniGamesModule`

Mini-game management and tracking functionality. Documentation

Usage Example

import { GamanzaEngageWebClientSDK } from '@gamanza-engage/web-client-sdk';
// Initialize the 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) {}
// Use SDK modules const playerData = await sdk.Player.getPlayerData(); const missions = await sdk.Missions.getActiveMissions();
// Always close the session when done await sdk.closeSession(); } catch (error) { console.error('SDK initialization failed:', error); }

Error Handling

The SDK throws the following exceptions:

`SDKNotInitializedException`

Thrown when attempting to get the SDK instance before initialization or after session closure.

Global Configuration

The SDK supports the following global configuration options:

`window.GMZ_ENG_DEBUG`

Set to true to enable debug logging throughout the SDK.

window.GMZ_ENG_DEBUG = true;

Important Notes

Singleton Pattern: The SDK uses a singleton pattern. Only one instance can exist at a time.
Initialization Required: Always call init() before using any SDK functionality.
Session Management: Always call closeSession() when finished to properly clean up resources and avoid issues with the player session data.
Error Handling: Implement proper error handling for all async operations.

Type Definitions

The SDK exports comprehensive type definitions for all interfaces and data structures. Import them alongside the main SDK class:

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

Change Log

Contents

1.8.0 (2025-12-02)

feat(GAM-2409): Add groupId field to admin reward events
- Updated rewardProcessor:on:claimRewardAdmin and rewardProcessor:on:rewardCancelled events to include the optional groupId field.
- Reflected changes in documentation and type definitions for consistency.
bugfix(TIP-174): Missing Mini Games Module on Barrel File
- Added MiniGamesModule to the index.ts file to export the module.

1.7.0 (2025-11-07)

feat(GAM-2382): Rewards Processor Adds the manual claim and canceled events to RTM Module

New Real-Time Events
- rewardProcessor:on:claimRewardAdmin: New event triggered when a reward is claimed by an admin operator
  - Properties: playerId, rewardType, rewardId, source, timestamp
  - Type: Direct | Guarantee: FIRE_FORGET
- rewardProcessor:on:rewardCancelled: New event triggered when a reward is cancelled by an admin operator
  - Properties: playerId, rewardType, rewardId, source, timestamp
  - Type: Direct | Guarantee: FIRE_FORGET
Socket Event Subscriptions
- Registered new admin reward claim and cancellation events in the socket client
- Improved cache synchronization with backend reward state changes

feat(PEPD-1546): Include groupId property in the event manualRewardAwarded

Event Data Structure Updates
- Added optional groupId field to ManualRewardAwardedEventData interface
- Enhanced metadata support with Record<string, unknown> for reward event data

feat(GAM-2414): Tournament Event for Admin Cancellation
- Add new RTM event tournaments:on:canceled to notify when admin cancels a tournament
- Register event listener in TournamentsModule to clear active tournaments cache on cancellation
- Update EventTypeMap interface with TournamentCanceledEventData type
- Include tournament cancellation event in socket client subscription list
- Document new event with payload structure and usage examples in rtm-events.module.md

feat(GAM-2413): Get player positions info for tournament leaderboard
- Added a new function called getPlayerLeaderboardsPositionInfo in the tournaments module to return the position information of the player for the given tournaments ids.
- Added TSDocs detailing the function functionality. Up to five tournament ids are supported per request.
- Updated the SDK docs to add developer docs for getPlayerLeaderboardsPositionInfo

1.6.0 (2025-10-15)

feat(Tournaments and Missions Buy-In): Enable Buy-In Support for Tournaments and Missions

Enhanced TournamentsModule and MissionsModule with comprehensive opt-in and buy-in support:

Core Interface Changes (commons.interface.ts)
- Added BuyInOptions enum to define entry types:
  - TOKENS: Token-based entry fee
  - FREE: No entry cost
- Centralized buy-in configuration for reuse across tournaments and missions
Tournament Interface Changes (tournaments.interface.ts)
- Extended TournamentType interface with new fields:
  - isPlayerOptIn: boolean flag indicating if player has opted into tournament
  - buyIn: Entry type configuration using BuyInOptions enum
  - buyOptions: Optional transaction details for tournament entry costs (tokens/currency)
- Enhanced JSDoc for optIn, buyIn, and buyOptions with detailed usage examples
- Updated field documentation with comprehensive type safety examples and use cases
- Improved documentation for winTxId and type fields with clarified descriptions
Tournament Module Implementation (tournaments.module.ts)
- Implemented playerOptInTournament() method for manual tournament registration
- Supports both free and token-based buy-in tournaments
- Validates player balance for token-based entries
- Returns HTTP 402 (Payment Required) for insufficient funds
- Automatically invalidates all tournament-related caches after successful opt-in
- Includes comprehensive JSDoc with error handling patterns and usage examples
Mission Interface Changes (missions.interface.ts)
- Extended MissionHistoryBundleDetailsType interface with new fields:
  - buyIn: Optional entry type configuration using BuyInOptions enum
  - buyOptions: Optional transaction details for mission bundle entry costs (tokens/currency)
- Added comprehensive JSDoc documentation with:
  - Token-based and cash-based entry patterns
  - Balance validation examples
  - UI rendering patterns for buy-in displays
  - Type guards for type-safe buy-in handling
Mission Module Implementation
- Enhanced playerRequestOptInMissionBundle() to support buy-in validation
- Supports both free and token-based mission bundle entries
- Validates player balance for token-based mission bundle entries
- Returns appropriate error codes for insufficient funds
- Automatically invalidates mission-related caches after successful opt-in

feat(Tournaments Win Multiplier): Tournaments win multiplier added to tournament event data

BREAKING CHANGES (Conditional only if is in use):

Removed TournamentTypeEnum.BONUS_BUY (not supported yet)
Updated tournament event data structures with stricter typing

Added:

RoundInfo discriminated union type for type-safe round data handling
- Automatically discriminates between CASINO and SPORT industry types
- CASINO rounds include required game property (GameInfoStruct)
- SPORT rounds include required sports property (SportInfoStruct[])
- Prevents invalid property access at compile time
RoundInfoBase type containing shared round properties
RoundIndustryPropertiesMap interface for mapping industry types to properties
GameInfoStruct type (gameId, gameName)
SportInfoStruct type (eventName, matchDate, sportName?)
Comprehensive JSDoc documentation for round-related fields

Enhanced LeaderboardPlayerType:

Added type field (TournamentTypeEnum) to identify tournament type
Added optional round field (RoundInfo) for highest win tournaments
Added JSDoc explaining when round data is available/undefined
Documented spinsLeft availability conditions

Enhanced PlayerLeaderboardUpdatedEventData:

Added type field to tournament entries
Added optional round field to tournament entries
Added detailed JSDoc for round field availability conditions

Improved TournamentsUpdatedEventData:

Refactored leaderboard type definition for better clarity
Simplified type intersection with Omit utility type

Updated Documentation:

Enhanced rtm-events.module.md with precise type information
Replaced generic any types with specific TypeScript types
Added proper type annotations for all tournament event properties
Improved type clarity for tournament event subscriptions

Technical Details:

Leverages TypeScript mapped types for automatic discriminated union generation
Maintains type safety through conditional property inclusion
Round data properly typed based on tournament industry type
Version bumped to 1.6.0

This implementation ensures compile-time type safety when working with tournament round data, preventing runtime errors from accessing properties that don't exist for a given tournament industry type.

1.5.0 (2025-10-02)

feat(Missions Opt In Addons): Missions Added new properties to for check opt-in requirements.
- Includes two new properties in the MissionHistoryBundleDetailsType interface and API response to include
  - playerRequiresOptIn: Determine if the Mission Bundle requires opt-In from the player to start the mechanic.
  - playerHasOptedIn: Determine if the player performed the opt-in action.
- Updated the getPlayerBundlesActive function in the Missions Module to allow developers to define the Cache TLL in seconds as an optional argument. Zero means no cache is applied.

1.4.0 (2025-09-23)

feat(Product Eligibility and Visibility): Determines which players can purchase the Product from the Rewards Shop
- Add comprehensive EligibilityMap and VisibilityMap interfaces with discriminated unions
- Implement type-safe productEligibility property in ProductType interface
- Introduce VisibilityOptions interface with country/rank filtering capabilities
- Enhance TypeScript type safety through union types and proper discrimination
- Optimize cache management by removing redundant product caching in getAllProducts()
- Reduce individual product cache TTL from 30 minutes to 15 minutes
- Update comprehensive documentation with detailed interface descriptions and usage examples
- Add JSDoc comments explaining eligibility rules, visibility options, and filter configurations
- Include practical code examples for eligibility type checking and error handling

1.3.0 (2025-09-17)

feat(GAM-2322): Integrate On Manual Reward Awarded Event
- Added a new RTM event called ON_MANUAL_REWARD_AWARDED to notify the player when a manual reward is awarded.
- Updated the SDK Docs to include this new event detail.

1.2.0 (2025-08-14)

feat(TIP-94): Add Opt-In/Opt-out option in SDK

Added two new functions to the Missions Module to allow players to opt-in or opt-out from a Mission Bundle:
- playerRequestOptInMissionBundle
- playerRequestOptOutMissionBundle
- Update missions module documentation

feat(TIP-93): Add a decline option for rewards in SDK
- Add playerRequestDeclineReward() method for individual reward decline
- Add playerRequestDeclineMissionRewards() method for bulk mission reward decline
- Add playerRequestDeclineRewardByGroupId() method for bulk player rewards deline
- Implement proper cache invalidation on reward state changes
- Add comprehensive error handling and response validation
- Update API endpoints to support new decline operations

1.1.0 (2025-08-11)

feat(GAM-2272): Include Mission and Bundle Ended events

Updated the RTM events to include the following events:
- ON_MISSION_ENDED: Event triggered when a mission is manually ended by an operator from the admin panel.
- ON_MISSION_BUNDLE_ENDED: Event triggered when a bundle is manually ended by an operator from the admin panel.
Updated the SDK Docs to include this new events detail.

📢 This SDK is proprietary. Use is governed by the Gamanza Engage SDK License Agreement. Redistribution or modification is strictly prohibited.

Overview​

Quickstart​

Before you begin​

Install the SDK​

Using the SDK​

Static Methods​

init(config: AuthConfig): Promise<GamanzaEngageWebClientSDK>​

getInstance(): GamanzaEngageWebClientSDK​

Instance Methods​

closeSession(): Promise<void>​

Public Modules​

Events: RtmEventsModule​

Player: PlayerModule​

RewardShop: RewardShopModule​

Missions: MissionsModule​

Tournaments: TournamentsModule​

RewardsProcessor: RewardsProcessorModule​

Crm: CrmModule​

FeatureFlags: FeatureFlagsModule​

Catalog: CatalogModule​

MiniGames: MiniGamesModule​

Usage Example​

Error Handling​

SDKNotInitializedException​

Global Configuration​

window.GMZ_ENG_DEBUG​

Important Notes​

Type Definitions​

Change Log​

1.8.0 (2025-12-02)​

1.7.0 (2025-11-07)​

1.6.0 (2025-10-15)​

1.5.0 (2025-10-02)​

1.4.0 (2025-09-23)​

1.3.0 (2025-09-17)​

1.2.0 (2025-08-14)​

1.1.0 (2025-08-11)​

Overview

Quickstart

Before you begin

Install the SDK

Using the SDK

Static Methods

`init(config: AuthConfig): Promise<GamanzaEngageWebClientSDK>`

`getInstance(): GamanzaEngageWebClientSDK`

Instance Methods

`closeSession(): Promise<void>`

Public Modules

`Events: RtmEventsModule`

`Player: PlayerModule`

`RewardShop: RewardShopModule`

`Missions: MissionsModule`

`Tournaments: TournamentsModule`

`RewardsProcessor: RewardsProcessorModule`

`Crm: CrmModule`

`FeatureFlags: FeatureFlagsModule`

`Catalog: CatalogModule`

`MiniGames: MiniGamesModule`

Usage Example

Error Handling

`SDKNotInitializedException`

Global Configuration

`window.GMZ_ENG_DEBUG`

Important Notes

Type Definitions

Change Log

1.8.0 (2025-12-02)

1.7.0 (2025-11-07)

1.6.0 (2025-10-15)

1.5.0 (2025-10-02)

1.4.0 (2025-09-23)

1.3.0 (2025-09-17)

1.2.0 (2025-08-14)

1.1.0 (2025-08-11)