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:
Name | Type | Description |
---|---|---|
event | keyof EventTypeMap | The event name to subscribe to |
callback | SDKEventListener<T> | The callback function that will be called when the event is triggered |
options | SubscriptionOptions (optional) | Additional options for the subscription |
Returns:
Type | Description |
---|---|
string | A 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:
Name | Type | Description |
---|---|---|
subscriptionId | string | The unique subscription ID returned by the subscribe method |
Returns:
Type | Description |
---|---|
boolean | true 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:
Name | Type | Description |
---|---|---|
event | keyof EventTypeMap | The event name to unsubscribe from |
Returns:
Type | Description |
---|---|
number | The 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:
Type | Description |
---|---|
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:
Name | Type | Description |
---|---|---|
event | keyof EmitterTypeMap | The event name to emit |
data | EmitterTypeMap[T] | The data to send with the event |
Returns:
Type | Description |
---|---|
void | This 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 Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
on:error | System error events | Direct | FIRE_FORGET | eventName: string , additional error properties |
Error Event Data Structure
interface ErrorEventData extends BaseEventData {
eventName: string;
[key: string]: unknown; // Additional error properties
}
Ranks Events
Event Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
ranks:on:xpUp | XP increase events | Direct | FIRE_FORGET | eventName: string , playerId: string , level: Level , nextLevel?: Level , nextRank?: Rank , pointsUntilNextLevel: number , pointsUntilNextRank: number , rank: Rank , xpBalance: number , rewardsGroupId: string |
ranks:on:levelUp | Level up events | Direct | FIRE_FORGET | eventName: 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:rankUp | Rank up events | Direct | FIRE_FORGET | eventName: 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:capReached | Maximum cap reached events | Direct | FIRE_FORGET | eventName: string , playerId: string , type: string , limit: number , period: string , reached: boolean |
ranks:on:levelBoosterActivated | Level booster activation events | Direct | FIRE_FORGET | eventName: 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:levelBoosterEnd | Level booster end events | Direct | FIRE_FORGET | eventName: 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:optIn | Gamification opt-in events | Direct | FIRE_FORGET | eventName: string , playerId: string , status: string |
ranks:on:optOut | Gamification opt-out events | Direct | FIRE_FORGET | eventName: 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 Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
virtualCurrency:on:walletUpdate | Wallet balance update events | Direct | FIRE_FORGET | eventName: string , balance: number , playerId: string |
virtualCurrency:on:tokenBoosterActivated | Token booster activation events | Direct | FIRE_FORGET | eventName: 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:tokenBoosterEnd | Token booster end events | Direct | FIRE_FORGET | eventName: 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 Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
missions:on:missionsBoosterActivated | Missions booster activation events | Direct | FIRE_FORGET | eventName: 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:missionsBoosterEnd | Missions booster end events | Direct | FIRE_FORGET | eventName: 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:objectiveUpdate | Mission objective update events | Direct | FIRE_FORGET | eventName: string , playerId: string , bundleId: string , bundleStateId: string , missionId: string , missionStateId: string , objectiveId: string , objectiveStateId: string , objectiveSummary: any , date: string |
missions:on:objectiveComplete | Mission objective completion events | Direct | FIRE_FORGET | eventName: string , playerId: string , bundleId: string , bundleStateId: string , missionId: string , missionStateId: string , objectiveId: string , objectiveStateId: string , objectiveSummary: any , date: string |
missions:on:missionUpdate | Mission update events | Direct | FIRE_FORGET | eventName: 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:missionComplete | Mission completion events | Direct | FIRE_FORGET | eventName: 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:missionBundleComplete | Mission bundle completion events | Direct | FIRE_FORGET | eventName: string , playerId: string , bundleId: string , status: string , bundleSummary: any , date: string |
missions:on:missionBundleAssign | Mission bundle assignment events | Direct | FIRE_FORGET | eventName: 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 Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
tournaments:on:beforeStarts | Tournament about to start events | Direct | FIRE_FORGET | eventName: 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:starts | Tournament start events | Direct | FIRE_FORGET | eventName: 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:ended | Tournament end events | Direct | FIRE_FORGET | eventName: 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:playerWonRewards | Tournament player won rewards events | Direct | FIRE_FORGET | eventName: 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:leaderboardUpdated | Tournament leaderboard update events | Broadcast | FIRE_FORGET | eventName: string , tournament: any , leaderboard: any , timestamp: string |
tournaments:on:playerLeaderboardUpdated | Player leaderboard update events | Direct | FIRE_FORGET | eventName: string , tournaments: { tournamentId: string, position: number, score: number, spinsLeft: number }[] , timestamp: string |
tournaments:on:spinsLeftEmpty | No spins left events | Direct | FIRE_FORGET | eventName: string , playerId: string , tournament: any |
tournaments:on:leaderboardReady | Leaderboard ready events | Broadcast | FIRE_FORGET | eventName: 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 Name | Description | Type | Guarantee Type | Properties |
---|---|---|---|---|
messageGateway:on:sendOnSiteNotification | On-site notification events | Direct | BEST_EFFORT | eventName: 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;
}
Related Interfaces
SubscriptionOptions
Interface for configuring event subscriptions.
interface SubscriptionOptions {
once?: boolean;
timeout?: number;
filter?: (data: any) => boolean;
maxRetries?: number;
autoAck?: boolean;
}
Property | Type | Description |
---|---|---|
once | boolean (optional) | If true , the subscription will be automatically removed after the first event is received |
timeout | number (optional) | Time in milliseconds after which the subscription will be automatically removed if no event is received |
filter | Function (optional) | A function that receives the event data and returns a boolean indicating whether the event should be processed |
maxRetries | number (optional) | Maximum number of retries for failed event processing |
autoAck | boolean (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;
Parameter | Type | Description |
---|---|---|
data | EventTypeMap[T] | The event data specific to the event type |
internalRawEvent | InternalRawEvent<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;
}
Property | Type | Description |
---|---|---|
id | string | The unique identifier of the event |
event | T | The event name |
data | EventTypeMap[T] | The event data |
timestamp | number | The timestamp when the event was generated |
guaranteeType | MessagingServiceGuaranteeType | The 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 Type | Description |
---|---|
FIRE_FORGET | Message is delivered to the player only if connected. If disconnected, the message is discarded. |
BEST_EFFORT | Message is delivered if connected. If disconnected, the message is stored and delivered on the next connection. |
RELIABLE_DELIVERY | Same as BEST_EFFORT, but waits for ACK notification before marking as delivered. |
RELIABLE_RECEIPT | Same 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 Name | Data Type | Description |
---|---|---|
send:ack | AckMessageEmitter | Acknowledgment message emitter for confirming receipt of events |
send:analytics:event | AnalyticsTrackingEventEmitter | Analytics tracking event emitter |
AckMessageEmitter
Interface for acknowledgment messages.
interface AckMessageEmitter {
messageId: string;
}
Property | Type | Description |
---|---|---|
messageId | string | The ID of the message being acknowledged |
AnalyticsTrackingEventEmitter
Interface for analytics tracking events.
interface AnalyticsTrackingEventEmitter {
eventName: string;
properties: Record<string, any>;
}
Property | Type | Description |
---|---|---|
eventName | string | The name of the analytics event |
properties | Record<string, any> | Additional properties for the analytics event |