Skip to main content

RTM Events Module

The RTM Events Module provides functionality for subscribing to and handling real-time events in the Gamanza Engage Web Client SDK. It allows developers to subscribe to various events, unsubscribe from events, and emit data to the WebSocket connection.

Accessing the Module

The RTM Events Module can be accessed through the Gamanza Engage SDK instance:

const rtmEvents = sdk.rtmEvents;

Public Methods

subscribe

Subscribes to receive real-time events based on the real-time communication API provided by Gamanza Engage.

Signature:

subscribe(event, callback, options)

Type Definition:

function subscribe<T extends keyof EventTypeMap>(
event: T,
callback: SDKEventListener<T>,
options?: SubscriptionOptions
): string;

Parameters:

NameTypeDescription
eventkeyof EventTypeMapThe event name to subscribe to
callbackSDKEventListener<T>The callback function that will be called when the event is triggered
optionsSubscriptionOptions (optional)Additional options for the subscription

Returns:

TypeDescription
stringA unique subscription ID that can be used to unsubscribe from the event

Example:

// Subscribe to XP up events
const subscriptionId = rtmEvents.subscribe('ranks:on:xpUp', (data, rawEvent) => {
console.log('Player XP increased:', data.xpBalance);
console.log('Raw event:', rawEvent);
});

// Subscribe with options
const optionsSubscriptionId = rtmEvents.subscribe('ranks:on:levelUp',
(data, rawEvent) => {
console.log('Player leveled up to:', data.level.levelNumber);
},
{
once: true, // Only trigger once
timeout: 60000, // Timeout after 60 seconds
filter: (data) => data.level.levelNumber > 5 // Only trigger for levels above 5
}
);

unsubscribe

Removes a single subscription by its identifier.

Signature:

unsubscribe(subscriptionId)

Type Definition:

function unsubscribe(subscriptionId: string): boolean;

Parameters:

NameTypeDescription
subscriptionIdstringThe unique subscription ID returned by the subscribe method

Returns:

TypeDescription
booleantrue if the subscription was successfully removed, false otherwise

Example:

// Unsubscribe from an event
const subscriptionId = rtmEvents.subscribe('ranks:on:xpUp', callback);
const unsubscribed = rtmEvents.unsubscribe(subscriptionId);

if (unsubscribed) {
console.log('Successfully unsubscribed from event');
} else {
console.log('Failed to unsubscribe or subscription not found');
}

unsubscribeFromEvent

Removes all active subscriptions for a specific event.

Signature:

unsubscribeFromEvent(event)

Type Definition:

function unsubscribeFromEvent<T extends keyof EventTypeMap>(event: T): number;

Parameters:

NameTypeDescription
eventkeyof EventTypeMapThe event name to unsubscribe from

Returns:

TypeDescription
numberThe number of subscriptions that were removed

Example:

// Unsubscribe from all XP up events
const removedCount = rtmEvents.unsubscribeFromEvent('ranks:on:xpUp');
console.log(`Removed ${removedCount} subscriptions`);

getEventsStats

Returns statistics about the current event subscriptions.

Signature:

getEventsStats()

Type Definition:

function getEventsStats(): Record<string, any>;

Parameters:

None

Returns:

TypeDescription
Record<string, any>An object containing statistics about the current event subscriptions

Example:

// Get subscription statistics
const stats = rtmEvents.getEventsStats();
console.log('Current subscriptions:', stats);

emitToWebSocket

Sends data using the Gamanza Engage Messaging Service (WebSockets).

Signature:

emitToWebSocket(event, data)

Type Definition:

function emitToWebSocket<T extends keyof EmitterTypeMap>(event: T, data: EmitterTypeMap[T]): void;

Parameters:

NameTypeDescription
eventkeyof EmitterTypeMapThe event name to emit
dataEmitterTypeMap[T]The data to send with the event

Returns:

TypeDescription
voidThis method does not return a value

Example:

// Send an acknowledgment message
rtmEvents.emitToWebSocket('send:ack', { messageId: 'message-123' });

// Send an analytics tracking event
rtmEvents.emitToWebSocket('send:analytics:event', {
eventName: 'button_click',
properties: {
buttonId: 'login-button',
timestamp: Date.now()
}
});

Events

The RTM Events Module provides access to various real-time events that can be subscribed to. These events are categorized into different groups based on their functionality.

System Events

Event NameDescriptionTypeGuarantee TypeProperties
on:errorSystem error eventsDirectFIRE_FORGETeventName: string, additional error properties

Error Event Data Structure

interface ErrorEventData extends BaseEventData {
eventName: string;
[key: string]: unknown; // Additional error properties
}

Ranks Events

Event NameDescriptionTypeGuarantee TypeProperties
ranks:on:xpUpXP increase eventsDirectFIRE_FORGETeventName: string, playerId: string, level: Level, nextLevel?: Level, nextRank?: Rank, pointsUntilNextLevel: number, pointsUntilNextRank: number, rank: Rank, xpBalance: number, rewardsGroupId: string
ranks:on:levelUpLevel up eventsDirectFIRE_FORGETeventName: string, playerId: string, level: Level, nextLevel?: Level, nextRank?: Rank, pointsUntilNextLevel: number, pointsUntilNextRank: number, rank: Rank, xpBalance: number, claimReward: true, rewards: Reward[], rewardsGroupId: string
ranks:on:rankUpRank up eventsDirectFIRE_FORGETeventName: string, playerId: string, level: Level, nextLevel?: Level, nextRank?: Rank, pointsUntilNextLevel: number, pointsUntilNextRank: number, rank: Rank, xpBalance: number, claimReward: boolean, rewards: Reward[], rewardsGroupId: string
capsMultipliers:on:capReachedMaximum cap reached eventsDirectFIRE_FORGETeventName: string, playerId: string, type: string, limit: number, period: string, reached: boolean
ranks:on:levelBoosterActivatedLevel booster activation eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: ActiveMetadataBoosterType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string
ranks:on:levelBoosterEndLevel booster end eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: ActiveMetadataBoosterType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string
ranks:on:optInGamification opt-in eventsDirectFIRE_FORGETeventName: string, playerId: string, status: string
ranks:on:optOutGamification opt-out eventsDirectFIRE_FORGETeventName: string, playerId: string, status: string

XP Up Event Data Structure

interface XpUpEventData extends BaseEventData {
eventName: string;
playerId: string;
level: {
_id: string;
levelNumber: number;
};
nextLevel?: {
_id: string;
levelNumber: number;
};
nextRank?: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
pointsUntilNextLevel: number;
pointsUntilNextRank: number;
rank: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
xpBalance: number;
rewardsGroupId: string;
}

Level Up Event Data Structure

interface LevelUpEventData extends BaseEventData {
eventName: string;
playerId: string;
level: {
_id: string;
levelNumber: number;
};
nextLevel?: {
_id: string;
levelNumber: number;
};
nextRank?: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
pointsUntilNextLevel: number;
pointsUntilNextRank: number;
rank: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
xpBalance: number;
claimReward: true;
rewards: Reward[];
rewardsGroupId: string;
}

Rank Up Event Data Structure

interface RankUpEventData extends BaseEventData {
eventName: string;
playerId: string;
level: {
_id: string;
levelNumber: number;
};
nextLevel?: {
_id: string;
levelNumber: number;
};
nextRank?: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
pointsUntilNextLevel: number;
pointsUntilNextRank: number;
rank: {
_id: string;
name: string;
imageUrl: string;
translations: {
language: string;
name: string;
description: string;
}[];
};
xpBalance: number;
claimReward: boolean;
rewards: Reward[];
rewardsGroupId: string;
}

Ranks Max Cap Reached Event Data Structure

interface RanksMaxCapReachedEventData extends BaseEventData {
eventName: string;
playerId: string;
type: string;
limit: number;
period: string;
reached: boolean;
}

Active Booster Event Data Structure

interface ActiveBoosterEventData extends BaseEventData {
eventName: string;
_id: string;
playerId: string;
rewardId: string;
boosterRate: number;
timeStart: string;
timeEnd: string;
status: string;
type: string;
boosterType?: RewardTypeEnum;
countDown?: {
days: number;
hours: number;
minutes: number;
seconds: number;
totalSeconds: number;
};
metadata?: {
[key: string]: unknown;
};
isNew?: boolean;
isRecentBooster?: boolean;
createAt?: string;
}

Gamification Opt Event Data Structure

interface GamificationOptEventData extends BaseEventData {
eventName: string;
playerId: string;
status: string;
}

Virtual Currency Events

Event NameDescriptionTypeGuarantee TypeProperties
virtualCurrency:on:walletUpdateWallet balance update eventsDirectFIRE_FORGETeventName: string, balance: number, playerId: string
virtualCurrency:on:tokenBoosterActivatedToken booster activation eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: ActiveMetadataBoosterType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string
virtualCurrency:on:tokenBoosterEndToken booster end eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: ActiveMetadataBoosterType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string

Wallet Update Event Data Structure

interface WalletUpdateEventData extends BaseEventData {
eventName: string;
balance: number;
playerId: string;
}

Missions Events

Event NameDescriptionTypeGuarantee TypeProperties
missions:on:missionsBoosterActivatedMissions booster activation eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: MissionBoosterMetadataType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string
missions:on:missionsBoosterEndMissions booster end eventsDirectFIRE_FORGETeventName: string, _id: string, playerId: string, rewardId: string, boosterRate: number, timeStart: string, timeEnd: string, status: string, type: string, boosterType?: RewardTypeEnum, countDown?: ActiveCountdownBoosterType, metadata?: MissionBoosterMetadataType, isNew?: boolean, isRecentBooster?: boolean, createAt?: string
missions:on:objectiveUpdateMission objective update eventsDirectFIRE_FORGETeventName: string, playerId: string, bundleId: string, bundleStateId: string, missionId: string, missionStateId: string, objectiveId: string, objectiveStateId: string, objectiveSummary: any, date: string
missions:on:objectiveCompleteMission objective completion eventsDirectFIRE_FORGETeventName: string, playerId: string, bundleId: string, bundleStateId: string, missionId: string, missionStateId: string, objectiveId: string, objectiveStateId: string, objectiveSummary: any, date: string
missions:on:missionUpdateMission update eventsDirectFIRE_FORGETeventName: string, playerId: string, easterEggs: any, _id: string, name: string, description: string, tags: string[], objectives: any[], validityTime: any, status: string, rewardCategories: any[], rewardClaimStatus: string, missionBundleState: any, bundleInternalDetails: any, bundleExternalDetails: any, enabled: boolean, version: number, state: string, missionBundleId: string, bundleStateId: string, missionId: string, endDate: string, startDate: string
missions:on:missionCompleteMission completion eventsDirectFIRE_FORGETeventName: string, playerId: string, easterEggs: any, _id: string, name: string, description: string, tags: string[], objectives: any[], validityTime: any, status: string, rewardCategories: any[], rewardClaimStatus: string, missionBundleState: any, bundleInternalDetails: any, bundleExternalDetails: any, enabled: boolean, version: number, state: string, missionBundleId: string, bundleStateId: string, missionId: string, endDate: string, startDate: string
missions:on:missionBundleCompleteMission bundle completion eventsDirectFIRE_FORGETeventName: string, playerId: string, bundleId: string, status: string, bundleSummary: any, date: string
missions:on:missionBundleAssignMission bundle assignment eventsDirectFIRE_FORGETeventName: string, playerId: string, missionBundleExternalDescription: any, date: string

Mission Booster Metadata Type Structure

interface MissionBoosterMetadataType {
missionId: string;
bundleId: string;
missionDescription: string;
missionBundleExternalDetails: {
language: string;
name: string;
description: string;
};
rewardId: string;
bundleStateId: string;
missionStateId: string;
[key: string]: unknown;
}

Mission Objective Event Data Structure

interface MissionObjectiveEventData extends BaseEventData {
eventName: string;
playerId: string;
bundleId: string;
bundleStateId: string;
missionId: string;
missionStateId: string;
objectiveId: string;
objectiveStateId: string;
objectiveSummary: {
_id: string;
conditionValue: string;
conditionType: string;
translations: Pick<TranslationType, 'language' | 'name' | 'description'>[];
missionEventType: string;
value: number;
completed: boolean;
state: MissionProgressType;
};
date: string;
}

Mission Update Event Data Structure

export interface MissionUpdateEventData extends BaseEventData {
_id: string;
name: string;
description: string;
tags: SlimTagType[];
objectives: ObjectiveMissionTypes[];
validityTime: ValidityTimeType | ValidityTimePeriodType | ValidityTimeSpecificDateType;
status: MissionStatusEnum;
rewardCategories: MissionRewardCategoryType[];
rewardClaimStatus?: MissionClaimStatusType;
missionBundleState?: MissionProgressType;
bundleInternalDetails: InternalDetailType;
bundleExternalDetails: TranslationType[];
enabled: boolean;
version: number;
state?: MissionProgressType;
missionBundleId?: string;
bundleStateId?: string;
missionId?: string;
endDate?: string;
startDate?: string;
originalMissionBundleId: string;
playerId: string;
repetitionCount?: number;
repetitionEnabled: boolean;
playerId: string;
easterEggs?: EasterEggsType[];
}

Mission Bundle Event Data Structure

interface MissionBundleEventData extends BaseEventData {
eventName: string;
playerId: string;
bundleId: string;
status: string;
bundleSummary: {
_id: string;
missionBundleExternalDescription: TranslationType;
state: MissionProgressType;
};
date: string;
}

Mission Bundle Assign Event Data Structure

interface MissionBundleAssignEventData extends BaseEventData {
eventName: string;
playerId: string;
missionBundleExternalDescription: TranslationType[];
date: string;
}

Tournaments Events

Event NameDescriptionTypeGuarantee TypeProperties
tournaments:on:beforeStartsTournament about to start eventsDirectFIRE_FORGETeventName: string, playerId: string, tournamentId: string, tournamentName: string, tournamentDescription: string, tournamentType: string, optIn: boolean, maxNumberOfBets: number, timePeriod: any, externalDetails: any, industry: TournamentIndustryTypeEnum, leaderboardRewards: LeaderboardReward[], timePeriod?: TimePeriodType;
tournaments:on:startsTournament start eventsDirectFIRE_FORGETeventName: string, playerId: string, tournamentId: string, tournamentName: string, tournamentDescription: string, tournamentType: string, optIn: boolean, maxNumberOfBets: number, timePeriod: any, externalDetails: any, industry: TournamentIndustryTypeEnum, leaderboardRewards: LeaderboardReward[], timePeriod?: TimePeriodType;
tournaments:on:endedTournament end eventsDirectFIRE_FORGETeventName: string, externalDetails: any, industry: string, maxNumberOfBets: number, optIn: boolean, timePeriod: any, tournamentDescription: string, tournamentId: string, tournamentName: string, tournamentType: string, leaderboardRewards: LeaderboardReward[], timePeriod?: TimePeriodType;, externalDetails: any
tournaments:on:playerWonRewardsTournament player won rewards eventsDirectFIRE_FORGETeventName: string, industry: string, maxNumberOfBets: number, optIn: boolean, timePeriod: any, tournamentDescription: string, tournamentId: string, tournamentName: string, tournamentType: string, leaderboard: { position: number }, leaderboardRewards: LeaderboardReward[], timePeriod?: TimePeriodType;, earnedRewards?: { [key: string]: Reward };
tournaments:on:leaderboardUpdatedTournament leaderboard update eventsBroadcastFIRE_FORGETeventName: string, tournament: any, leaderboard: any, timestamp: string
tournaments:on:playerLeaderboardUpdatedPlayer leaderboard update eventsDirectFIRE_FORGETeventName: string, tournaments: { tournamentId: string, position: number, score: number, spinsLeft: number }[], timestamp: string
tournaments:on:spinsLeftEmptyNo spins left eventsDirectFIRE_FORGETeventName: string, playerId: string, tournament: any
tournaments:on:leaderboardReadyLeaderboard ready eventsBroadcastFIRE_FORGETeventName: string, tournamentId: string, externalDetails: any, leaderboardRewards: LeaderboardReward[], eligibility: any, timePeriod?: TimePeriodType;, eligibility: TournamentEligibilityType

Tournament Notifications Event Data Structure

interface TournamentNotificationsEventData extends BaseEventData {
eventName: string;
playerId: string;
tournamentId: string;
tournamentName: string;
tournamentDescription: string;
tournamentType: string;
optIn: boolean;
maxNumberOfBets: number;
timePeriod: any;
externalDetails: ExternalDetailsEntity[];
industry: TournamentIndustryTypeEnum;
leaderboardRewards: LeaderboardReward[];
timePeriod?: TimePeriodType;
}

Tournament Ended Event Data Structure

interface TournamentEndedEventData extends BaseEventData {
eventName: string;
externalDetails: any;
industry: string;
leaderboardRewards: any[];
maxNumberOfBets: number;
optIn: boolean;
timePeriod: any;
tournamentDescription: string;
tournamentId: string;
tournamentName: string;
tournamentType: string;
}

Tournament Player Won Event Data Structure

interface TournamentPlayerWonEventData extends BaseEventData {
eventName: string;
earnedRewards: any;
externalDetails: any;
industry: string;
leaderboardRewards: any[];
maxNumberOfBets: number;
optIn: boolean;
timePeriod: any;
tournamentDescription: string;
tournamentId: string;
tournamentName: string;
tournamentType: string;
leaderboard: {
position: number;
};
}

Tournaments Updated Event Data Structure

interface TournamentsUpdatedEventData extends BaseEventData {
eventName: string;
tournament: any;
leaderboard: any;
timestamp: string;
}

Player Leaderboard Updated Event Data Structure

interface PlayerLeaderboardUpdatedEventData extends BaseEventData {
eventName: string;
tournaments: {
tournamentId: string;
position: number;
score: number;
spinsLeft: number;
}[];
timestamp: string;
}

Spins Left Empty Event Data Structure

interface SpinsLeftEmptyEventData extends BaseEventData {
eventName: string;
playerId: string;
tournament: TournamentEventData;
}

Tournament Leaderboard Ready Structure

interface TournamentLeaderboardReady extends BaseEventData {
eventName: string;
tournamentId: string;
externalDetails: any;
leaderboardRewards: LeaderboardReward[];
eligibility: TournamentEligibilityType;
}

CRM Events

Event NameDescriptionTypeGuarantee TypeProperties
messageGateway:on:sendOnSiteNotificationOn-site notification eventsDirectBEST_EFFORTeventName: string, msg: { type: string, contentHtml: string, language: string }, playerId: string

On-Site Notification Event Data Structure

interface OnSiteNotificationEventData extends BaseEventData {
eventName: string;
msg: {
type: string;
contentHtml: string;
language: string;
};
playerId: string;
}

SubscriptionOptions

Interface for configuring event subscriptions.

interface SubscriptionOptions {
once?: boolean;
timeout?: number;
filter?: (data: any) => boolean;
maxRetries?: number;
autoAck?: boolean;
}
PropertyTypeDescription
onceboolean (optional)If true, the subscription will be automatically removed after the first event is received
timeoutnumber (optional)Time in milliseconds after which the subscription will be automatically removed if no event is received
filterFunction (optional)A function that receives the event data and returns a boolean indicating whether the event should be processed
maxRetriesnumber (optional)Maximum number of retries for failed event processing
autoAckboolean (optional)If true, events will be automatically acknowledged. Default is false

SDKEventListener

Type definition for event listener callbacks.

type SDKEventListener<T extends keyof EventTypeMap> = (
data: EventTypeMap[T],
internalRawEvent: InternalRawEvent<T>
) => void;
ParameterTypeDescription
dataEventTypeMap[T]The event data specific to the event type
internalRawEventInternalRawEvent<T>The raw event data received from the server

InternalRawEvent

Interface representing the raw event data received from the server.

interface InternalRawEvent<T extends keyof EventTypeMap> {
id: string;
event: T;
data: EventTypeMap[T];
timestamp: number;
guaranteeType: MessagingServiceGuaranteeType;
}
PropertyTypeDescription
idstringThe unique identifier of the event
eventTThe event name
dataEventTypeMap[T]The event data
timestampnumberThe timestamp when the event was generated
guaranteeTypeMessagingServiceGuaranteeTypeThe guarantee type of the event

MessagingServiceGuaranteeType

An enum defining different guarantee levels for message delivery.

enum MessagingServiceGuaranteeType {
FIRE_FORGET = 'FIRE_FORGET',
BEST_EFFORT = 'BEST_EFFORT',
RELIABLE_DELIVERY = 'RELIABLE_DELIVERY',
RELIABLE_RECEIPT = 'RELIABLE_RECEIPT',
}
Guarantee TypeDescription
FIRE_FORGETMessage is delivered to the player only if connected. If disconnected, the message is discarded.
BEST_EFFORTMessage is delivered if connected. If disconnected, the message is stored and delivered on the next connection.
RELIABLE_DELIVERYSame as BEST_EFFORT, but waits for ACK notification before marking as delivered.
RELIABLE_RECEIPTSame as BEST_EFFORT, but the origin microservice is notified when the message is delivered.

EmitterTypeMap

A mapping of emitter event names to their corresponding data types.

interface EmitterTypeMap {
'send:ack': AckMessageEmitter;
'send:analytics:event': AnalyticsTrackingEventEmitter;
}
Event NameData TypeDescription
send:ackAckMessageEmitterAcknowledgment message emitter for confirming receipt of events
send:analytics:eventAnalyticsTrackingEventEmitterAnalytics tracking event emitter

AckMessageEmitter

Interface for acknowledgment messages.

interface AckMessageEmitter {
messageId: string;
}
PropertyTypeDescription
messageIdstringThe ID of the message being acknowledged

AnalyticsTrackingEventEmitter

Interface for analytics tracking events.

interface AnalyticsTrackingEventEmitter {
eventName: string;
properties: Record<string, any>;
}
PropertyTypeDescription
eventNamestringThe name of the analytics event
propertiesRecord<string, any>Additional properties for the analytics event