Skip to main content
Gamanza Engage

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​

  1. Understand the APIs you need to implement
  2. Create a Client Id
  3. Set up authentication

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();

or

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

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​

  1. Singleton Pattern: The SDK uses a singleton pattern. Only one instance can exist at a time.

  2. Initialization Required: Always call init() before using any SDK functionality.

  3. Session Management: Always call closeSession() when finished to properly clean up resources and avoid issues with the player session data.

  4. 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.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.