Player Module

The Player Module provides access to player information and gamification preferences in the Gamanza Engage Web Client SDK.

Accessing the Module

The PlayerModule is initialized internally by the SDK and should not be instantiated directly. It's accessible through the main SDK instance.

// Example of accessing the PlayerModule through the SDK
const { Player } = GamanzaEngageWebClientSDK.getInstance();

Methods

getPlayer

Returns the current authenticated player information from the Gamanza Engage Platform.

Signature:

getPlayer(): Promise<PlayerData | null>

Returns:

Type	Description
Promise<PlayerData | null>	A promise that resolves to the player data or null if the player is missing or there is an error.

Example:

// Get player information
const player = await sdk.Player.getPlayer();
if (player) {
  console.log(`Player ID: ${player.playerId}`);
  console.log(`Player Name: ${player.firstName} ${player.lastName}`);
  
  // Access gamification status
  console.log(`Gamification Enabled: ${player.gamificationOpt.enable}`);
  
  // Access ranks data if available
  if (player.ranksData) {
    console.log(`Current Rank: ${player.ranksData.rank.name}`);
    console.log(`Current Level: ${player.ranksData.level.levelNumber}`);
    console.log(`XP Balance: ${player.ranksData.xpBalance}`);
  }
  
  // Access wallet data if available
  if (player.walletData) {
    console.log(`Wallet Balance: ${player.walletData.balance}`);
  }
}

playerGamificationOpts

Allows enabling or disabling the Gamanza Engage Gamification features for the current authenticated player.

Signature:

playerGamificationOpts(enable: boolean, reasons: Reason[]): Promise<SimpleResponse<void>>

Parameters:

Name	Type	Description
enable	boolean	Defines if the player opts in (true) or opts out (false)
reasons	Reason[]	List of potential reasons why the player is opting out (required when opting out)

Returns:

Type	Description
Promise<SimpleResponse<void>>	A promise that resolves to a simple response indicating success or failure

Example:

// Opt out of gamification with reasons
const reasons = await sdk.Player.getListOfOptOutReasons();
const selectedReasons = [reasons[0]]; // Select first reason from the list

const response = await sdk.Player.playerGamificationOpts(false, selectedReasons);
if (response.ok) {
  console.log('Successfully opted out of gamification');
} else {
  console.error('Failed to opt out of gamification:', response.error);
}

// Opt in to gamification (no reasons needed)
const optInResponse = await sdk.Player.playerGamificationOpts(true, []);
if (optInResponse.ok) {
  console.log('Successfully opted in to gamification');
}

getListOfOptOutReasons

Returns the list of predefined reasons configured in the Gamanza Engage Admin Instance to be displayed to the player when they decide to opt out of gamification.

Signature:

getListOfOptOutReasons(): Promise<Reason[]>

Returns:

Type	Description
Promise<Reason[]>	A promise that resolves to an array of predefined opt-out reasons

Example:

// Get list of opt-out reasons
const reasons = await sdk.Player.getListOfOptOutReasons();
console.log('Available opt-out reasons:');
reasons.forEach(reason => {
  // Display the reason in the user's language if available
  const translation = reason.translations?.find(t => t.language === userLanguage);
  console.log(translation?.text || reason.option);
});

Related Interfaces

PlayerData

The main interface for player information.

interface PlayerData {
  playerId: string;
  firstName?: string;
  lastName?: string;
  gender?: string;
  phone?: string;
  username?: string;
  email?: string;
  language?: string;
  currency?: string;
  birthDate?: string;
  nationality?: string;
  address?: Address;
  session?: PlayerSession;
  gamificationOpt: GamificationOpt;
  ranksData?: RanksData;
  walletData?: WalletData;
}

Property	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
firstName	string	No	Player's first name
lastName	string	No	Player's last name
gender	string	No	Player's gender
phone	string	No	Player's phone number
username	string	No	Player's username
email	string	No	Player's email address
language	string	No	Player's preferred language
currency	string	No	Player's preferred currency
birthDate	string	No	Player's birth date
nationality	string	No	Player's nationality
address	Address	No	Player's address information
session	PlayerSession	No	Player's session information
gamificationOpt	GamificationOpt	Yes	Player's gamification preferences
ranksData	RanksData	No	Player's rank information
walletData	WalletData	No	Player's wallet information

Address

Interface for player address information.

interface Address {
  country?: string;
  city?: string;
  street?: string;
  postcode?: string;
}

Property	Type	Required	Description
country	string	No	Player's country
city	string	No	Player's city
street	string	No	Player's street address
postcode	string	No	Player's postal code

PlayerSession

Interface for player session information.

interface PlayerSession {
  registrationDate?: string;
  registrationDevice?: string;
  verificationDate?: string;
  verificationChannel?: string;
  numberDaysInLastTwoLogins?: number;
  lastLoginDate?: string;
  secondLastLoginDate?: string;
  loginCount?: number;
  lastLogoutDate?: string;
}

Property	Type	Required	Description
registrationDate	string	No	Date when the player registered
registrationDevice	string	No	Device used for registration
verificationDate	string	No	Date when the player was verified
verificationChannel	string	No	Channel used for verification
numberDaysInLastTwoLogins	number	No	Number of days between the last two logins
lastLoginDate	string	No	Date of the player's last login
secondLastLoginDate	string	No	Date of the player's second-to-last login
loginCount	number	No	Total number of logins
lastLogoutDate	string	No	Date of the player's last logout

GamificationOpt

Interface for player gamification preferences.

interface GamificationOpt {
  enable: boolean;
  reason?: Reason[];
  resetPolicy?: Record<string, unknown>;
  requestedByType?: string;
  requestedBy?: string;
  requestedAt?: string;
}

Property	Type	Required	Description
enable	boolean	Yes	Whether gamification is enabled for the player
reason	Reason[]	No	Reasons for opting out of gamification
resetPolicy	Record<string, unknown>	No	Policy for resetting gamification
requestedByType	string	No	Type of entity that requested the gamification status change
requestedBy	string	No	Entity that requested the gamification status change
requestedAt	string	No	Date when the gamification status change was requested

Reason

Interface for opt-out reasons.

interface Reason {
  option?: string;
  translations?: Translation[];
}

Property	Type	Required	Description
option	string	No	Identifier for the reason
translations	Translation[]	No	Translations of the reason text

Translation

Interface for translations.

interface Translation {
  language?: string;
  text?: string;
}

Property	Type	Required	Description
language	string	No	Language code
text	string	No	Translated text

RanksData

Interface for player rank information.

interface RanksData {
  _id: string;
  playerId: string;
  category: Category;
  rank: Rank;
  level: Level;
  xpBalance: number;
  createdAt: string;
  updatedAt: string;
  currency: string;
  previousPeriod?: PreviousPeriod;
  rankProgress: number;
  levelProgress: number;
  levelPosition?: LevelPosition;
  pointsUntilNextLevel: number;
  pointsUntilNextRank: number;
  nextLevel?: Level;
  nextRank?: Rank;
  pointsToKeepRank?: number;
  xpComparativePeriod?: string;
  betActivity?: BetActivityType;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the ranks data
playerId	string	Yes	Player identifier
category	Category	Yes	Rank category
rank	Rank	Yes	Current rank
level	Level	Yes	Current level
xpBalance	number	Yes	Current XP balance
createdAt	string	Yes	Creation date
updatedAt	string	Yes	Last update date
currency	string	Yes	Currency used
previousPeriod	PreviousPeriod	No	Data from the previous period
rankProgress	number	Yes	Progress towards the next rank (0-100)
levelProgress	number	Yes	Progress towards the next level (0-100)
levelPosition	LevelPosition	No	Position within the current level
pointsUntilNextLevel	number	Yes	Points needed to reach the next level
pointsUntilNextRank	number	Yes	Points needed to reach the next rank
nextLevel	Level	No	Next level information
nextRank	Rank	No	Next rank information
pointsToKeepRank	number	No	Points needed to maintain the current rank
xpComparativePeriod	string	No	Period used for XP comparison
betActivity	BetActivityType	No	Betting activity information

Category

Interface for rank categories.

interface Category {
  _id: string;
  name: string;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the category
name	string	Yes	Category name

Rank

Interface for player ranks.

interface Rank {
  _id: string;
  name: string;
  imageUrl: string;
  translations: RanksTranslation[];
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the rank
name	string	Yes	Rank name
imageUrl	string	Yes	URL to the rank image
translations	RanksTranslation[]	Yes	Translations of the rank information

Level

Interface for player levels.

interface Level {
  _id: string;
  levelNumber: number;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the level
levelNumber	number	Yes	Level number

WalletData

Interface for player wallet information.

interface WalletData {
  _id: string;
  balance: number;
  createdAt: string;
  updatedAt: string;
}

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the wallet
balance	number	Yes	Current wallet balance
createdAt	string	Yes	Creation date
updatedAt	string	Yes	Last update date

SimpleResponse

Generic interface for simple responses.

interface SimpleResponse<T> {
  ok: boolean;
  data: T | null;
  error?: {
    code: string;
    message: string;
  };
}

Property	Type	Required	Description
ok	boolean	Yes	Whether the operation was successful
data	T | null	Yes	Response data (null for void responses)
error	{ code: string; message: string; }	No	Error information if the operation failed