Module: player

Table of contents

Functions

• canSubscribeBotAsync
• flushDataAsync
• getASIDAsync
• getConnectedPlayersAsync
• getDataAsync
• getID
• getName
• getPhoto
• getSignedASIDAsync
• getSignedPlayerInfoAsync
• getTokenAsync
• isFirstPlay
• onLogin
• setDataAsync
• showAuthPromptAsync
• showLinkAccountPromptAsync
• subscribeBotAsync

Functions

canSubscribeBotAsync

▸ canSubscribeBotAsync(): Promise<boolean>

Checks if the current user can subscribe to the game's bot.

Example

Wortal.player.canSubscribeBotAsync()
.then(canSubscribe => console.log("Can subscribe to bot: " + canSubscribe));

Returns

Promise<boolean>

Promise that resolves whether a player can subscribe to the game bot or not. Developer can only call player.subscribeBotAsync() after checking player.canSubscribeBotAsync(), and the game will only be able to show the player their bot subscription dialog once per week.

Throws

• NOT_SUPPORTED
• RATE_LIMITED
• INVALID_OPERATION
• CLIENT_UNSUPPORTED_OPERATION

---

flushDataAsync

▸ flushDataAsync(): Promise<void>

Flushes any unsaved data to the platform's storage. This function is expensive, and should primarily be used for critical changes where persistence needs to be immediate and known by the game. Non-critical changes should rely on the platform to persist them in the background.

NOTE: Calls to player.setDataAsync will be rejected while this function's result is pending.

Example

Wortal.player.flushDataAsync()
 .then(() => console.log("Data flushed."));

Returns

Promise<void>

Promise that resolves when changes have been persisted successfully, and rejects if the save fails.

Throws

• NOT_SUPPORTED
• INVALID_PARAM
• NETWORK_FAILURE
• PENDING_REQUEST
• CLIENT_UNSUPPORTED_OPERATION

---

getASIDAsync

▸ getASIDAsync(): Promise<string>

A unique identifier for the player. This is the standard Facebook Application-Scoped ID which is used for all Graph API calls. If your game shares an AppID with a native game this is the ID you will see in the native game too.

Example

Wortal.player.getASIDAsync()
.then(asid => console.log("Player ASID: " + asid));

Returns

Promise<string>

A unique identifier for the player. String is nullable.

Throws

• NOT_SUPPORTED
• RETHROW_FROM_PLATFORM

---

getConnectedPlayersAsync

▸ getConnectedPlayersAsync(payload?): Promise<ConnectedPlayer[]>

Fetches an array of ConnectedPlayer objects containing information about active players that are connected to the current player.

PLATFORM NOTE: Facebook does not support the payload parameter or any filters, it will always return the list of connected players who have played the game in the last 90 days. Facebook also requires the user_data permission to be granted to the game in order to use this API.

Example

Wortal.player.getConnectedPlayersAsync({
    filter: 'ALL',
    size: 20,
    hoursSinceInvitation: 4,
}).then(players => console.log(players.length));

Parameters

Name	Type	Description
payload?	ConnectedPlayerPayload	Options for the friends to get.

Returns

Promise<ConnectedPlayer[]>

Promise that resolves with a list of connected player objects.

Throws

• NOT_SUPPORTED
• NETWORK_FAILURE
• CLIENT_UNSUPPORTED_OPERATION

---

getDataAsync

▸ getDataAsync(keys): Promise<any>

Retrieve data from the designated cloud storage of the current player.

PLATFORM NOTE: JSON objects stored as string values will be returned back as JSON objects on Facebook.

Example

Wortal.player.getDataAsync(['items', 'lives'])
 .then(data => {
     console.log(data['items']);
     console.log(data['lives']);
 });

Parameters

Name	Type	Description
keys	string[]	Array of keys for the data to get.

Returns

Promise<any>

Promise that resolves with an object which contains the current key-value pairs for each key specified in the input array, if they exist.

Throws

• NOT_SUPPORTED
• INVALID_PARAM
• NETWORK_FAILURE
• CLIENT_UNSUPPORTED_OPERATION

---

getID

▸ getID(): string | null

Gets the player's ID from the platform.

Example

Wortal.player.getID(); // 'Player123ABC'

Returns

string | null

The player's ID.

---

getName

▸ getName(): string | null

Gets the player's name on the platform.

Example

Wortal.player.getName(); // 'Ragnar Lothbrok'

Returns

string | null

The player's name.

---

getPhoto

▸ getPhoto(): string | null

Gets the player's photo from the platform.

Example

Wortal.player.getPhoto();

Returns

string | null

URL of image for the player's photo.

---

getSignedASIDAsync

▸ getSignedASIDAsync(): Promise<SignedASID>

A unique identifier for the player. This is the standard Facebook Application-Scoped ID which is used for all Graph API calls. If your game shares an AppID with a native game this is the ID you will see in the native game too.

Example

Wortal.player.getSignedASIDAsync()
 .then(info => {
    myServer.validate(
    info.asid,
    info.signature,
    );
  });

Returns

Promise<SignedASID>

Promise that resolves with an object containing player ASID and signature.

Throws

• NOT_SUPPORTED
• RETHROW_FROM_PLATFORM

---

getSignedPlayerInfoAsync

▸ getSignedPlayerInfoAsync(): Promise<object>

Gets a signed player object that includes the player ID and signature for validation. This can be used to send something to a backend server for validation, such as game or purchase data.

Example

Wortal.player.getSignedPlayerInfoAsync()
 .then(info => {
     myServer.validate(
         info.id,
         info.signature,
         gameDataToValidate,
     )
 });

Returns

Promise<object>

Promise that resolves with an object containing the player ID and signature.

Throws

• NOT_SUPPORTED
• INVALID_PARAM
• NETWORK_FAILURE
• CLIENT_UNSUPPORTED_OPERATION

---

getTokenAsync

▸ getTokenAsync(): Promise<string>

Gets the player token from the platform.

Example

Wortal.player.getTokenAsync()
.then(token => console.log("Player token: " + token));

Returns

Promise<string>

Promise that resolves with the player token.

Throws

• AUTH_NOT_ENABLED
• USER_NOT_AUTHENTICATED
• UNKNOWN
• NOT_SUPPORTED

---

isFirstPlay

▸ isFirstPlay(): boolean

Checks whether this is the first time the player has played this game.

Example

if (Wortal.player.isFirstPlay()) {
   // Show tutorial
   Wortal.player.setDataAsync({ tutorialShown: true });
}

Returns

boolean

True if it is the first play. Some platforms do not have data persistence and always return true.

---

onLogin

▸ onLogin(callback): void

Registers a callback to be called when the player logs in or registers for an account.

Example

Wortal.player.onLogin(() => console.log("Player logged in or registered"));

Parameters

Name	Type	Description
callback	() => void	Callback to be called when the player logs in or registers for an account.

Returns

void

Throws

• NOT_SUPPORTED

---

setDataAsync

▸ setDataAsync(data): Promise<void>

Set data to be saved to the designated cloud storage of the current player.

PLATFORM NOTE: Facebook/Link allow storage up to 1MB of data for each unique player.

PLATFORM NOTE: Viber allows storage up to 1000 characters when stringified.

Example

Wortal.player.setDataAsync({
    items: {
        coins: 100,
        boosters: 2
    },
    lives: 3,
});

Parameters

Name	Type	Description
data	Record<string, unknown>	An object containing a set of key-value pairs that should be persisted to cloud storage. The object must contain only serializable values - any non-serializable values will cause the entire modification to be rejected.

Returns

Promise<void>

Promise that resolves when the input values are set.

NOTE: The promise resolving does not necessarily mean that the input has already been persisted. Rather, it means that the data was valid and has been scheduled to be saved. It also guarantees that all values that were set are now available in player.getDataAsync.

Throws

• NOT_SUPPORTED
• INVALID_PARAM
• NETWORK_FAILURE
• PENDING_REQUEST
• CLIENT_UNSUPPORTED_OPERATION

---

showAuthPromptAsync

▸ showAuthPromptAsync(): Promise<void>

Shows the authentication prompt to the player. This allows the player to log in or register for an account. If the player successfully logs in or registers, the player API will be updated with the new player information.

Example

Wortal.player.showAuthPromptAsync()
.then(() => console.log("Player logged in or registered"));

Returns

Promise<void>

Promise that resolves when the player has logged in or registered.

Throws

• AUTH_IN_PROGRESS
• USER_ALREADY_AUTHENTICATED
• USER_INPUT
• NOT_SUPPORTED

---

showLinkAccountPromptAsync

▸ showLinkAccountPromptAsync(): Promise<boolean>

Shows the link account prompt to the player. This allows the player to link their account to a different platform.

Example

Wortal.player.showLinkAccountPromptAsync()
.then(isLinked => console.log("Player linked account: " + isLinked));

Returns

Promise<boolean>

Promise that resolves when the player has linked their account.

Throws

• LINK_IN_PROGRESS
• USER_NOT_AUTHENTICATED
• NOT_SUPPORTED

---

subscribeBotAsync

▸ subscribeBotAsync(): Promise<void>

Request that the player subscribe the bot associated to the game. The API will reject if the subscription fails - else, the player will subscribe the game bot.

Example

Wortal.player.subscribeBotAsync()
.then(() => console.log("Player subscribed to bot"));

Returns

Promise<void>

Promise that resolves if player successfully subscribed to the game bot, or rejects if request failed or player chose to not subscribe.

Throws

• NOT_SUPPORTED
• INVALID_PARAM
• PENDING_REQUEST
• CLIENT_REQUIRES_UPDATE