Instant Games

Instant Games SDK v8.0: FBInstant.player

Updated: May 14, 2026
Copy for LLM
See Instant Games SDK v8.0 for the SDK overview, changelog, and root FBInstant reference.

FBInstant.player

getID()

A unique identifier for the player. A Facebook user’s player ID will remain constant, and is scoped to a specific game. This means that different games will have different player IDs for the same user. This function should not be called until FBInstant.initializeAsync() has resolved.
Returns:?string — A unique identifier for the player.
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
var playerID = FBInstant.player.getID();

getASIDAsync()

NOTE: This function will only return ASIDs for users migrating over from your canvas app or for users that had previously accepted Terms of Service for you game. You should rely on player ID for all of your use cases.
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.
Returns:Promise<?string> — A unique identifier for the player.
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
var playerASID = FBInstant.player.getASIDAsync().then(
 asid => console.log(asid);
);

getAgeCategoryAsync()

Returns the age category of the current player. The age category is determined by the player’s date of birth and can be used to enable age-appropriate content and features in your game.
Returns:Promise<string> — A promise that resolves with the age category string: - ‘TN’ (Teen): Player is 13-17 years old - ‘AD’ (Adult): Player is 18+ years old - ‘UNKNOWN’: Age information is not available
Throws:
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.player.getAgeCategoryAsync()
  .then(function(ageCategory) {
    if (ageCategory === 'TN') {
      disableAdultContent();
    }
  });

getSignedASIDAsync()

NOTE: This function will only return ASIDs for users migrating over from your canvas app or for users that had previously accepted Terms of Service for you game. You should rely on player ID for all of your use * cases. 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.
Returns:Promise<?SignedASID> — A promise that resolves with a SignedASID object.
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
var playerASID = FBInstant.player.getSignedASIDAsync()
  .then(function (result) {
    result.getASID();
  });

getSignedAssociatedAppsASIDAsync()

Returns a list of associated apps and their corresponding ASIDs with signatures for the current player. Associated apps are pre-approved Instant Games, native apps, or Canvas Games linked to the current game. Each entry includes a cryptographic signature so your server can verify that the ASID came from Facebook and was not tampered with.
Returns:Promise<?Array<SignedAssociatedAppASID>> — A promise that resolves with an array of SignedAssociatedAppASID objects, or null if no associated apps exist.
Throws:
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.player.getSignedAssociatedAppsASIDAsync()
  .then(function(associatedApps) {
    if (associatedApps) {
      associatedApps.forEach(function(app) {
        console.log('App ID: ' + app.getAppID());
        console.log('ASID: ' + app.getASID());
        console.log('Signature: ' + app.getSignature());
      });
    }
  });

getSignedPlayerInfoAsync()

Fetch the player’s unique identifier along with a signature that verifies that the identifier indeed comes from Facebook without being tampered with. This function should not be called until FBInstant.initializeAsync() has resolved.
Parameters:
ParameterTypeDescription
requestPayload
string(optional)
A developer-specified payload to include in the signed response.
Returns:Promise<SignedPlayerInfo> — A promise that resolves with a SignedPlayerInfo object.
Throws:
  • INVALID_PARAM
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
Example:
// This function should be called after FBInstant.initializeAsync()
// resolves.
FBInstant.player.getSignedPlayerInfoAsync('my_metadata')
  .then(function (result) {
    // The verification of the ID and signature should happen on server side.
    SendToMyServer(
      result.getPlayerID(), // same value as FBInstant.player.getID()
      result.getSignature(),
      'GAIN_COINS',
      100);
  });

canSubscribeBotAsync()

Returns a promise that resolves with whether the player can subscribe to the game bot or not.
Returns:Promise<boolean> — Whether a player can subscribe to the game bot or not. Developer can only call subscribeBotAsync() after checking canSubscribeBotAsync(), and the game will only be able to show the player their bot subscription dialog once per week.
Throws:
  • RATE_LIMITED
  • INVALID_OPERATION
  • CLIENT_UNSUPPORTED_OPERATION
Example:
// This function should be called before FBInstant.player.subscribeBotAsync()
FBInstant.player.canSubscribeBotAsync().then(
  can_subscribe => console.log(can_subscribe)
);
// 'true'

isSubscribedBotAsync()

Returns a promise that resolves with whether the player is already subscribed to the game bot or not.
Returns:Promise<boolean> — Whether a player is already subscribed to the game bot or not. This is to perform custom logic for players who are subscribed to the game bot. To check whether to prompt the user to subscribe, canSubscribeBotAsync should be used instead.
Example:
FBInstant.player.isSubscribedBotAsync()
  .then(function (isSubscribed) {
    // Custom logic
  })
)

subscribeBotAsync()

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.
Returns:Promise — A promise that resolves if player successfully subscribed to the game bot, or rejects if request failed or player chose to not subscribe.
Throws:
  • INVALID_PARAM
  • PENDING_REQUEST
  • CLIENT_REQUIRES_UPDATE
Example:
FBInstant.player.subscribeBotAsync().then(
  // Player is subscribed to the bot
).catch(function (e) {
  // Handle subscription failure
});

getDataAsync()

Retrieve data from the designated cloud storage of the current player. In SDK v8.0, values stored as JSON strings are returned as strings. Parse returned string values in your game code if you need JavaScript objects.
Parameters:
ParameterTypeDescription
keys
Array<string>
An array of unique keys to retrieve data for.
Returns:Promise.<Object> — A 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:
  • INVALID_PARAM
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.player
  .getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
     console.log('data is loaded');
     var achievements = data['achievements'];
     var currentLife = data['currentLife'];
  });

setDataAsync()

Set data to be saved to the designated cloud storage of the current player. The game can store up to 1MB of data for each unique player.
Parameters:
ParameterTypeDescription
data
Object
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 — A 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:
  • INVALID_PARAM
  • NETWORK_FAILURE
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(function() {
    console.log('data is set');
  });

flushDataAsync()

Immediately flushes any changes to the player data to the designated cloud 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.
Returns:Promise — A promise that resolves when changes have been persisted successfully, and rejects if the save fails.
Throws:
  • INVALID_PARAM
  • NETWORK_FAILURE
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(FBInstant.player.flushDataAsync)
  .then(function() {
    console.log('Data persisted to FB!');
  });

getConnectedPlayersAsync()

Fetches an array of ConnectedPlayer objects containing player IDs of active players (people who played the game in the last 90 days) that are connected to the current player.
Returns:Promise<Array<ConnectedPlayer>> — A promise that resolves with a list of connected player objects. NOTE: This function should not be called until FBInstant.initializeAsync() has resolved.
Throws:
  • NETWORK_FAILURE
  • CLIENT_UNSUPPORTED_OPERATION
Example:
var connectedPlayers = FBInstant.player.getConnectedPlayersAsync()
  .then(function(players) {
    console.log(players.map(function(player) {
      return {
        id: player.getID(),
      }
    }));
  });
// [{id: '123456789'}, {id: '987654321'}]

createNEZPNotificationContentAsync()

Creates notification content for use in a Network Enabled Zero Permissions (NEZP) environment. The content includes an image overlay rendered from XML/CSS, a title, an optional subtitle, and optional initial data. The generated image and text are stored on Meta servers and can be referenced later when sending notifications via the A2U Graph API. See more details in the A2U API.
This function should not be called until FBInstant.initializeAsync() has resolved.
Parameters:
ParameterTypeDescription
payload
CreateNEZPNotificationContentPayload
The notification content payload object. See properties below.
Payload properties:
PropertyTypeRequiredDescription
imageOverlayPath
string
Yes
Path to the XML overlay view file that defines the notification image layout.
pathToCSS
string
Yes
Path to the CSS file for styling the overlay view.
notificationTitle
string
Yes
The notification title. Supports template tokens such as ``.
notificationSubtitle
string
No
An optional subtitle for the notification.
initialData
Object
No
Optional developer-defined data passed to the overlay view for rendering.
recipients
Array<string>
No
Player IDs of valid recipients. Recipients must be part of the current game context.
Returns:Promise<string> — A promise that resolves with a notification_content_id string. Use this ID with the notifications Graph API to send the notification to the specified recipients.
Throws:
  • INVALID_PARAM
  • NETWORK_FAILURE
  • PENDING_REQUEST
Example:
await FBInstant.player.createNEZPNotificationContentAsync({
  imageOverlayPath: 'ig_views/profile_view.xml',
  pathToCSS: 'ig_views/styles.css',
  initialData: {wordSubmitted: 'APPLE'},
  notificationTitle: ' just took their turn!',
  notificationSubtitle: 'It is your turn now!',
  recipients: ['6719542978151885'],
}).then((notificationContentId) =>
  console.log('Notification content created with ID: ' + notificationContentId)
).catch((error) =>
  console.error('Failed to create notification:', error.code, error.message)
);

Types

SignedPlayerInfo

Represents information about the player along with a signature to verify that it indeed comes from Facebook.

getPlayerID()

Get the id of the player.
Returns:string — The ID of the player
Example:
FBInstant.player.getSignedPlayerInfoAsync()
  .then(function (result) {
    result.getPlayerID(); // same value as FBInstant.player.getID()
  });

getSignature()

A signature to verify this object indeed comes from Facebook. The string is base64url encoded and signed with an HMAC version of your App Secret, based on the OAuth 2.0 spec.
You can validate it with the following 5 steps:
  1. Split the signature into two parts delimited by the ‘.’ character.
  2. Decode the first part (the encoded signature) with base64url encoding.
  3. Decode the second part (the response payload) with base64url encoding, which should be a string representation of a JSON object that has the following fields: algorithm - always equals to HMAC-SHA256 issued_at - a unix timestamp of when this response was issued. player_id - unique identifier of the player. request_payload - the requestPayload string you specified when calling FBInstant.player.getSignedPlayerInfoAsync.
  4. Hash the whole response payload string using HMAC SHA-256 and your app secret and confirm that it is equal to the encoded signature.
  5. You may also wish to validate the issued_at timestamp in the response payload to ensure the request was made recently.
Signature validation should only happen on your server. Never do it on the client side as it will compromise your app secret key.
Returns:string — The signature string.
Example:
FBInstant.player.getSignedPlayerInfoAsync()
  .then(function (result) {
    result.getSignature();
    // Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ
  });

SignedPlayerInfoData

Data structure containing player information and signature.
Properties:
PropertyTypeDescription
playerID
string
- The unique identifier of the player.
signature
string
- The signature to verify the player information.

SignedASID

Represents app-scoped user id of current player along with a signature to verify that it indeed comes from Facebook.

getASID()

Get the app-scoped user id of the player.
Returns:string — The ID of the player
Example:
FBInstant.player.getSignedASIDAsync()
  .then(function (result) {
    result.getASID();
  });

getSignature()

A signature to verify this object indeed comes from Facebook. The string is base64url encoded and signed with an HMAC version of your App Secret, based on the OAuth 2.0 spec.
You can validate it with the following 5 steps:
  1. Split the signature into two parts delimited by the ‘.’ character.
  2. Decode the first part (the encoded signature) with base64url encoding.
  3. Decode the second part (the response payload) with base64url encoding, which should be a string representation of a JSON object that has the following fields: algorithm - always equals to HMAC-SHA256 issued_at - a unix timestamp of when this response was issued. asid - the app-scoped user id of the player.
  4. Hash the whole response payload string using HMAC SHA-256 and your app secret and confirm that it is equal to the encoded signature.
  5. You may also wish to validate the issued_at timestamp in the response payload to ensure the request was made recently.
Signature validation should only happen on your server. Never do it on the client side as it will compromise your app secret key.
Returns:string — The signature string.
Example:
FBInstant.player.getSignedASIDAsync()
  .then(function (result) {
    result.getSignature();
  });

SignedASIDData

Data structure containing app-scoped user ID and signature.
Properties:
PropertyTypeDescription
asid
string
- The app-scoped user ID of the player.
signed_request
string
- The signature to verify the ASID information.

SignedAssociatedAppASID

Represents an associated app ID and ASID for the current player along with a signature to verify that the data indeed comes from Facebook.

getAppID()

Get the associated app ID.
Returns:string — The associated app ID
Example:
FBInstant.player.getSignedAssociatedAppsASIDAsync()
  .then(function(associatedApps) {
    if (associatedApps) {
      associatedApps.forEach(function(app) {
        console.log('App ID: ' + app.getAppID());
      });
    }
  });

getASID()

Get the app-scoped user ID for the associated app.
Returns:string — The ASID for the associated app

getSignature()

Get the signature to verify the associated app ASID information.
Returns:string — The signature string

SignedAssociatedAppASIDData

Data structure containing associated app ID, app-scoped user ID, and signature.
Properties:
PropertyTypeDescription
app_id
string
- The associated app ID.
asid
string
- The app-scoped user ID for the associated app.
signed_request
string
- The signature to verify the associated app ASID information.