Stats APIs (getStatsAsync(), setStatsAsync() and incrementStatsAsync()) have been fully removed on September 28th, 2022.
Top level namespace for the Instant Games SDK.
Contains functions and properties related to Graph APIs
Performs a graph API Call and returns the result.
path
string The graph API path to perform the request against.method
string? HTTP method that will be used for this request. GET
is the default if not specified.params
Object? Parameters that will be sent as part of the request.FBInstant.graphApi.requestAsync('/me?fields=id,name') .then(function(response) { ... });
Returns Promise<Object> the result of the graph API call.
Contains functions and properties related to instant tournaments.
Posts a player's score to Facebook. This API should only be called within a tournament context at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be consistent and comparable across game sessions. For example, if Player A achieves 200 points in a session, and Player B achieves 320 points in a session, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.
score
number An integer value representing the player's score at
the end of an activity.function onScore(score) { if (score > bestScore) { bestScore = score; FBInstant.tournament.postScoreAsync(bestScore) .then(function() { ... }); } }
Returns Promise A promise that resolves when the score post is completed.
Opens the tournament creation dialog if the player is not currently in a tournament session
payload
CreateTournamentPayload
Throws INVALID_PARAM
Returns Promise<Tournaments.Tournament>
Opens the reshare tournament dialog if the player is currently in a tournament session
payload
ShareTournamentPayload Specifies share content. See example for
details.FBInstant.tournament.shareAsync({ score: 3, data: { myReplayData: '...' } }).then(function() { // continue with the game. });
Returns Promise A promise that resolves if the tournament is shared, or rejects otherwise.
Request a switch into a specific tournament context. If the player is not a participant of the tournament, or there are not any connected players participating in the tournament, this will reject. Otherwise, the promise will resolve when the game has switched into the specified context.
FBInstant.getTournamentAsync().then((tournament) => { console.log(tournament.getID()); }); // 1122334455 FBInstant.tournament .joinAsync('1122334455') .then(function() { // Context switch completed successfully. });
Returns Promise A promise that resolves when the game has switched into the specified tournament context, or rejects otherwise.
Returns a list of eligible tournaments that can be surfaced in-game, including tournaments 1) the player has created; 2) the player is participating in; 3) the player's friends (who granted permission) are participating in. The instant tournaments returned are active. An instant tournament is expired if its end time is in the past. For each instant tournament, there is only one unique context ID linked to it, and that ID doesn't change.
FBInstant.tournament.getTournamentsAsync() .then(tournaments => { // tournament list });
Returns Promise<Array<Tournaments.Tournament>>
[IN CLOSED BETA] Contains functions and properties related to game inventory.
[IN CLOSED BETA] This API represents a template for unlockable items. This feature is currently in beta and its usage will expand soon.
unlockableItemConfig
UnlockableItemConfig The unlockable item's
configuration details.FBInstant.inventory.unlockItemAsync({ name: 'item1', }).then(function (unlockableItemStat) { console.log(unlockableItemStat); // {downloaded: true} });
Returns Promise<UnlockableItemStat> A Promise that resolves when the item is unlockable for the player. Otherwise, it rejects.
Contains functions and properties related to the current player.
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.
// This function should be called after FBInstant.initializeAsync() // resolves. var playerID = FBInstant.player.getID();
Returns string? A unique identifier for the player.
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.
// This function should be called after FBInstant.initializeAsync() // resolves. var playerASID = FBInstant.player.getASIDAsync().then( asid => console.log(asid); );
Returns Promise<string?> A unique identifier for the player.
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.
// This function should be called after FBInstant.initializeAsync() // resolves. var playerASID = FBInstant.player.getSignedASIDAsync() .then(function (result) { result.getASID(); });
Returns Promise<SignedASID?> A promise that resolves with a SignedASID object.
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.
requestPayload
string? A developer-specified payload to include
in the signed response.// 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); });
Returns Promise<SignedPlayerInfo> A promise that resolves with a SignedPlayerInfo object.
Returns a promise that resolves with whether the player can subscribe to the game bot or not.
// This function should be called before FBInstant.player.subscribeBotAsync() FBInstant.player.canSubscribeBotAsync().then( can_subscribe => console.log(can_subscribe) ); // 'true'
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.
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.
FBInstant.player.subscribeBotAsync().then( // Player is subscribed to the bot ).catch(function (e) { // Handle subscription failure });
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.
The player's localized display name. This function should not be called until FBInstant.initializeAsync() has resolved.
// This function should be called after FBInstant.initializeAsync() // resolves. var playerName = FBInstant.player.getName();
Returns string? The player's localized display name.
A url to the player's public profile photo. The photo will always be a square, and with dimensions of at least 200x200. When rendering it in the game, the exact dimensions should never be assumed to be constant. It's recommended to always scale the image to a desired size before rendering. The value will always be null until FBInstant.initializeAsync() resolves.
WARNING: Due to CORS, using these photos in the game canvas can cause it to be tainted, which will prevent the canvas data from being extracted. To prevent this, set the cross-origin attribute of the images you use to 'anonymous'.
var playerImage = new Image(); playerImage.crossOrigin = 'anonymous'; // This function should be called after FBInstant.initializeAsync() // resolves. playerImage.src = FBInstant.player.getPhoto();
Returns string? Url to the player's public profile photo.
Retrieve data from the designated cloud storage of the current player. Please note that JSON objects stored as string values would be returned back as JSON objects.
FBInstant.player .getDataAsync(['achievements', 'currentLife']) .then(function(data) { console.log('data is loaded'); var achievements = data['achievements']; var currentLife = data['currentLife']; });
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.
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.
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.FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(function() { console.log('data is set'); });
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.
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.
FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(FBInstant.player.flushDataAsync) .then(function() { console.log('Data persisted to FB!'); });
Returns Promise A promise that resolves when changes have been persisted successfully, and rejects if the save fails.
Fetches an array of ConnectedPlayer objects containing information about active players (people who played the game in the last 90 days) that are connected to the current player.
var connectedPlayers = FBInstant.player.getConnectedPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); }); // [{id: '123456789', name: 'Paul Atreides'}, {id: '987654321', name: 'Duncan Idaho'}]
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.
Contains functions and properties related to the current game context.
A unique identifier for the current game context. This represents a specific context that the game is being played in (for example, a facebook post). The identifier will be null if game is being played in a solo context. This function should not be called until FBInstant.startGameAsync has resolved.
// This function should be called after FBInstant.initializeAsync() // resolves. var contextID = FBInstant.context.getID();
Returns string? A unique identifier for the current game context.
The type of the current game context. POST - A facebook post. THREAD - A chat thread. GROUP - A facebook group. SOLO - Default context, where the player is the only participant.
This function should not be called until FBInstant.startGameAsync has resolved.
// This function should be called after FBInstant.initializeAsync() // resolves. var contextType = FBInstant.context.getType();
Returns ("POST"
| "THREAD"
| "GROUP"
| "SOLO"
) Type of the current game context.
This function determines whether the number of participants in the current game context is between a given minimum and maximum, inclusive. If one of the bounds is null only the other bound will be checked against. It will always return the original result for the first call made in a context in a given game play session. Subsequent calls, regardless of arguments, will return the answer to the original query until a context change occurs and the query result is reset. This function should not be called until FBInstant.startGameAsync has resolved.
console.log(FBInstant.context.isSizeBetween(3, 5)); (Context size = 4) // {answer: true, minSize: 3, maxSize: 5}
console.log(FBInstant.context.isSizeBetween(5, 7)); (Context size = 4) // {answer: false, minSize: 5, maxSize: 7}
console.log(FBInstant.context.isSizeBetween(2, 10)); (Context size = 3) // {answer: true, minSize: 2, maxSize: 10} console.log(FBInstant.context.isSizeBetween(4, 8)); (Still in same context) // {answer: true, minSize: 2, maxSize: 10}
console.log(FBInstant.context.isSizeBetween(3, null)); (Context size = 4) // {answer: true, minSize: 3, maxSize: null}
console.log(FBInstant.context.isSizeBetween(null, 3)); (Context size = 4) // {answer: false, minSize: null, maxSize: 3}
console.log(FBInstant.context.isSizeBetween("test", 5)); (Context size = 4) // null
console.log(FBInstant.context.isSizeBetween(0, 100)); (Context size = null) // null
Returns (ContextSizeResponse | null)
Request a switch into a specific context. If the player does not have permission to enter that context, or if the player does not provide permission for the game to enter that context, this will reject. Otherwise, the promise will resolve when the game has switched into the specified context.
id
string ID of the desired context or the string SOLO to
switch into a solo context.switchSilentlyIfSolo
boolean If switching into a solo context,
set this to true to switch silently, with no confirmation dialog
or toast. This only has an effect when switching into a solo context. (optional, default false
)console.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .switchAsync('1234567890') .then(function() { console.log(FBInstant.context.getID()); // 1234567890 });
Returns Promise A promise that resolves when the game has switched into the specified context, or rejects otherwise.
Opens a context selection dialog for the player. If the player selects an available context, the client will attempt to switch into that context, and resolve if successful. Otherwise, if the player exits the menu or the client fails to switch into the new context, this function will reject.
options
Object? An object specifying conditions on the contexts
that should be offered.options.filters
Array<ContextFilter>? The set of filters to
apply to the context suggestions.options.maxSize
number? The maximum number of participants that
a suggested context should ideally have.options.minSize
number? The minimum number of participants that
a suggested context should ideally have.console.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .chooseAsync() .then(function() { console.log(FBInstant.context.getID()); // 1234567890 });
console.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .chooseAsync({ filters: ['NEW_CONTEXT_ONLY'], minSize: 3, }) .then(function() { console.log(FBInstant.context.getID()); // 1234567890 });
Returns Promise A promise that resolves when the game has switched into the context chosen by the user. Otherwise, the promise will reject (if the user cancels out of the dialog, for example).
Attempts to create a context between the current player and a specified player or a list of players. This API supports 3 use cases: 1) When the input is a single playerID, it attempts to create or switch into a context between a specified player and the current player 2) When the input is a list of connected playerIDs, it attempts to create a context containing all the players 3) When there's no input, a friend picker will be loaded to ask the player to create a context with friends to play with
For each of these cases, the returned promise will reject if any of the players listed are not Connected Players of the current player, or if the player denies the request to enter the new context. Otherwise, the promise will resolve when the game has switched into the new context.
suggestedPlayerIDs
(string | Array<string>)? null
(string | Array<String>) ?suggestedPlayerIDs A list of game suggested
playerIDs or a single suggested playerID or no inputconsole.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .createAsync('12345678') .then(function() { console.log(FBInstant.context.getID()); // 5544332211 });
console.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .createAsync(['12345678', '87654321']) .then(function() { console.log(FBInstant.context.getID()); // 55443322112232 });
console.log(FBInstant.context.getID()); // 1122334455 FBInstant.context .createAsync() .then(function() { console.log(FBInstant.context.getID()); // 55443322112232 });
Returns Promise A promise that resolves when the game has switched into the new context, or rejects otherwise.
Gets an array of ContextPlayer objects containing information about active players in the current context (people who played the game in the current context in the last 90 days). This may include the current player.
var contextPlayers = FBInstant.context.getPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); }); // [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}]
Returns Promise<Array<ContextPlayer>>
Contains functions and properties related to gaming squads.
Brings up a dialog for the player to join a Squad if they are not part of it. If the user accepts, they become part of the squad thread and the game context switches into the squad. If they are part of the Squad already, the dialog will prompt the user to switch into the Squad context.
payload
JoinGamingSquadPayload? FBInstant.squads.getAsync(squadID) .then(function(squad) { squad.joinAsync().then(...) });
Returns Promise
Brings up a dialog for the player to confirm if they want to leave the Squad. If the player confirms, they are removed from the Squad and the messenger thread that is associated with this Squad.
payload
LeaveGamingSquadPayload? FBInstant.squads.getAsync(squadID) .then(function(squad) { squad.leaveAsync().then(...) });
Returns Promise
Brings up a dialog for the player to add their friends to the current squad.
payload
AddToGamingSquadPayload? FBInstant.squads.getAsync(squadID) .then(function(squad) { squad.addToSquadAsync().then(...) });
Returns Promise
Brings up a dialog for the player to create a Squad. If the player creates the Squad, the promise will resolve with the new Squad instance and the game session will be switched into this newly created Squad context. The promise will reject if the player closes the dialog instead
payload
CreateGamingSquadPayload? FBInstant.squads.createAsync() .then(function(squad) { ... });
Returns Promise<GamingSquad>
Fetch an existing Squad. If the Squad does not exist, or the player cannot interact with the Squad, this API will reject with the GAMING_SQUAD_NOT_FOUND error code.
id
string The squad ID or context IDFBInstant.squads.getAsync(squadID) .then(function(squad) { console.log(squad.getID()) });
Returns Promise<GamingSquad>
Fetches the current player's existing squads, if any.
FBInstant.squads.getPlayerSquadsAsync() .then(function(squads) { squads.forEach(squad => console.log(squad.getID())); });
Returns Promise<Array<GamingSquad>>
Fetches the current player's existing squads, if any.
FBInstant.squads.canUseSquadsAsync() .then(function(isEligible) { if (isEligible) { FBInstant.squads.getAsync(squadID) .then(function(squad) { console.log(squad.getID()) }); } });
Returns Promise<boolean> Returns whether the current user is eligible to use squads
Contains functions and properties related to arenas.
Brings up a dialog showing Arena details and prompting the user to register for the Arena if the user is not registered to it already. If the user click on 'Register', they become registered to the Arena, but if the user dimisses the dialog, USER_INPUT error will be thrown
FBInstant.arenas.getArenasAsync() .then(function(arenas) { arenas.forEach(arena => arena.registerAsync().then(...)); });
Returns Promise
Fetches the all the NOT_STARTED and RUNNING arenas that belong to the game.
FBInstant.arenas.getArenasAsync() .then(function(arenas) { arenas.forEach(arena => console.log(arena.getID())); });
[IN CLOSED BETA] Contains functions and properties related to gaming community.
Check if user can get live streams
FBInstant.community.canGetLiveStreamsAsync() .then(function(data) { console.log(data); });
Returns Promise<boolean> Returns bool for whether user/game can get live streams
Check if user can follow official game page
FBInstant.community.canFollowOfficialPageAsync() .then(function(data) { console.log(data); });
Returns Promise<boolean> Returns bool for whether user can follow official game page
Check if user can join official game group
FBInstant.community.canJoinOfficialGroupAsync() .then(function(data) { console.log(data); });
Returns Promise<boolean> Returns bool for whether user can join official game group
getLiveStreamsAsync
is deprecated. Use liveStreamsOverlayAsync
instead.
Renders overlay with grid of live streams
FBInstant.community.liveStreamsOverlayAsync()
Returns Promise
Renders overlay with follow official page CTA
FBInstant.community.followOfficialPageAsync()
Returns Promise
Renders overlay with join group CTA
FBInstant.community.joinOfficialGroupAsync()
Returns Promise
[IN CLOSED BETA] Contains functions and properties related to live comment views.
Creates a live comment view
channelID
string ID of the live comment view to display.initialState
LiveVideoCommentViewState? Initial state of the comment view.
Optional. Defaults value is { show: true } (optional, default {}
)FBInstant.liveVideoCommentView.createAsync(channelID) .then(function(liveVideoCommentView) { console.log(liveVideoCommentView.getChannelID()); });
Returns Promise<LiveVideoCommentView>
Contains functions and properties related to the messenger rooms environment.
Shows the AR effect for the user in the room session. If the user has a non-game effect applied, it will prompt the user for permission for the first time. If the user denis, the promise is rejected, otherwise it is resolved after applying the effect
FBInstant.room.loadCameraEffectAsync() .then(function(effect) { effect.showAsync().then(() => console.log("Effect shown")); });
Returns Promise Resolves when the effect is applied to the player
Retrieves the current real-time match for the gameplay environment, if one exists.
FBInstant.room.getCurrentMatchAsync() .then(function(match) { ... });
Retrieves and loads a specified AR effect that has been registered for the game
cameraEffectArgs
CameraEffectArgs The args representing the effect to be loaded. See example for detailsFBInstant.room.loadCameraEffectAsync({effectID: '123'}) .then(function(effect) { ... });
Returns Promise<CameraEffect>
Clears the current AR effect in the rooms call. If an effect is present that was not applied by the game, the player will be prompted to approve the removal of the effect. The API will resolve after the effect is cleared, or will reject if the user denies the effect removal.
FBInstant.room.clearCameraEffectAsync() .then(function() { ... });
Returns Promise Resolves if the effect is cleared
Contains functions and properties related to payments and purchases of game products.
Fetches the game's product catalog.
FBInstant.payments.getCatalogAsync().then(function (catalog) { console.log(catalog); // [{productID: '12345', ...}, ...] });
Returns Promise<Array<Product>> The set of products that are registered to the game.
Begins the purchase flow for a specific product. Will immediately reject if called before FBInstant.startGameAsync() has resolved.
purchaseConfig
PurchaseConfig The purchase's configuration details.FBInstant.payments.purchaseAsync({ productID: '12345', developerPayload: 'foobar', }).then(function (purchase) { console.log(purchase); // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...} });
Returns Promise<Purchase> A Promise that resolves when the product is successfully purchased by the player. Otherwise, it rejects.
Fetches all of the player's unconsumed purchases. The game must fetch the current player's purchases as soon as the client indicates that it is ready to perform payments-related operations, i.e. at game start. The game can then process and consume any purchases that are waiting to be consumed.
FBInstant.payments.getPurchasesAsync().then(function (purchases) { console.log(purchase); // [{productID: '12345', ...}, ...] });
Returns Promise<Array<Purchase>> The set of purchases that the player has made for the game.
Consumes a specific purchase belonging to the current player. Before provisioning a product's effects to the player, the game should request the consumption of the purchased product. Once the purchase is successfully consumed, the game should immediately provide the player with the effects of their purchase.
purchaseToken
string The purchase token of the purchase that should
be consumed.FBInstant.payments.consumePurchaseAsync('54321').then(function () { // Purchase successfully consumed! // Game should now provision the product to the player });
Returns Promise A Promise that resolves when the purchase has been consumed successfully.
Sets a callback to be triggered when Payments operations are available.
callback
Function The callback function to be executed when Payments
are available.FBInstant.payments.onReady(function () { console.log('Payments Ready!') });
Returns void
[IN CLOSED BETA]
Fetches the game's catalog for subscribable products.
FBInstant.payments.getSubscribableCatalogAsync().then(function (catalog) { console.log(catalog); // [{productID: '12345', ...}, ...] });
Returns Promise<Array<SubscribableProduct>> The set of subscribable products that are registered to the game.
[IN CLOSED BETA]
Begins the purchase subscription flow for a specific product. Will immediately reject if called before FBInstant.startGameAsync() has resolved and fail if the product id passes is not that of a subscribable product
productID
string The subscribable product id that will be purchasedFBInstant.payments.purchaseSubscriptionAsync('12345').then(function (subscription) { console.log(subscription); });
Returns Promise<Subscription> A Promise that resolves when the subscription is successfully purchased by the player. Otherwise, it rejects.
[IN CLOSED BETA]
Fetches all of the player's subscriptions.
FBInstant.payments.getSubscriptionsAsync().then(function (subscriptions) { console.log(subscriptions); // [{productID: '12345', ...}, ...] });
Returns Promise<Array<Subscription>> The set of subscription purchases' that the player has made for the game.
[IN CLOSED BETA]
Starts the asynchronous process of cancelling an existing subscription. This operation will only work if the subscription entitlement is active. If the promise is resolved, this is only an indication that the cancellation has been kicked off and NOT that it has necessarily succeeded.
The subscription's deactivationTime
and isEntitlementActive
properties
should be queried for the latest status.
purchaseToken
string The purchase token of the purchase that should
be consumed.FBInstant.payments.cancelSubscriptionAsync('54321').then(function () { // Subscription cancellation in-progress });
Returns Promise A Promise that resolves when the purchase has been consumed successfully.
Contains functions and properties related to interactive streams.
Creates a video player embedded in the game. The video player can play a live stream or offline video based on the video ID specified.
videoID
string ID of the video to be played.initialState
VideoPlayerInstanceState Initial state of the video.
Optional. Defaults value is { mute: false, show: true, play: true,
loop: false } with the video covering the entire instant games container.FBInstant.videoPlayer.createAsync(videoID) .then(function(videoPlayerInstance) { console.log(videoPlayerInstance.getCurrentTimestamp()); });
Returns Promise<VideoPlayerInstance>
Returns the full set of video instances created.
FBInstant.videoPlayer.getInstancesAsync() .then(function(instances) { console.log(instances.length); });
Returns Promise<Array<VideoPlayerInstance>>
The current locale. See https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml for a complete list of supported locale values. Use this to determine what languages the current game should be localized with. The value will not be accurate until FBInstant.initializeAsync() resolves.
// This function should be called after FBInstant.initializeAsync() // resolves. var locale = FBInstant.getLocale(); // 'en_US'
Returns string The current locale.
The platform on which the game is currently running. The value will always be null until FBInstant.initializeAsync() resolves.
// This function should be called after FBInstant.initializeAsync() // resolves. var platform = FBInstant.getPlatform(); // 'IOS'
Returns (Platform | null)
The string representation of this SDK version.
// This function should be called after FBInstant.initializeAsync() // resolves. var sdkVersion = FBInstant.getSDKVersion(); // '2.0'
Returns string The SDK version.
Initializes the SDK library. This should be called before any other SDK functions.
FBInstant.initializeAsync().then(function() { // Many properties will be null until the initialization completes. // This is a good place to fetch them: var locale = FBInstant.getLocale(); // 'en_US' var platform = FBInstant.getPlatform(); // 'IOS' var sdkVersion = FBInstant.getSDKVersion(); // '3.0' var playerID = FBInstant.player.getID(); });
Returns Promise A promise that resolves when the SDK is ready to use.
Report the game's initial loading progress.
percentage
number A number between 0 and 100.FBInstant.setLoadingProgress(50); // Assets are 50% loaded
Returns void
Provides a list of API functions that are supported by the client.
// This function should be called after FBInstant.initializeAsync() // resolves. FBInstant.getSupportedAPIs(); // ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...]
Returns Array<string> List of API functions that the client explicitly supports.
Returns any data object associated with the entry point that the game was launched from.
The contents of the object are developer-defined, and can occur from entry points on different platforms. This will return null for older mobile clients, as well as when there is no data associated with the particular entry point.
This function should be called after FBInstant.initializeAsync() resolves.
// This function should be called after FBInstant.initializeAsync() // resolves. const entryPointData = FBInstant.getEntryPointData();
Returns Object? Data associated with the current entry point.
Returns the entry point that the game was launched from.
This function should not be called until FBInstant.startGameAsync has resolved.
// This function should be called after FBInstant.initializeAsync() // resolves. FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint)); // 'admin_message'
Returns string The name of the entry point from which the user started the game
Sets the data associated with the individual gameplay session for the current context.
This function should be called whenever the game would like to update the current session data. This session data may be used to populate a variety of payloads, such as game play webhooks.
sessionData
Object An arbitrary data object, which must be less
than or equal to 1000 characters when stringified.FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]});
Returns void
This indicates that the game has finished initial loading and is ready to start. Context information will be up-to-date when the returned promise resolves.
FBInstant.startGameAsync().then(function() { myGame.start(); });
Returns Promise A promise that resolves when the game should start.
[IN CLOSED BETA] Contains functions and properties related to in-game achievements.
[IN CLOSED BETA] Returns an ID of the Facebook video which launched this game.
FBInstant.getEntryPointVideoIDAsync() .then(function(videoID) { console.log('User entered game from video ' + videoID); });
Returns Promise<(string | null)>
This invokes a dialog to let the user invite one or more people to the game. A blob of data can be attached to the invite which every game session launched from the invite will be able to access from FBInstant.getEntryPointData(). This data must be less than or equal to 1000 characters when stringified. The user may choose to cancel the action and close the dialog, and the returned promise will resolve when the dialog is closed regardless of whether the user actually invited people or not. The sections included in the dialog can be customized by using the sections parameter. This can specify which sections to include, how many results to include in each section, and what order the sections should appear in. The last section will include as many results as possible. If no sections are specified, the default section settings will be applied. The filters parameter allows for filtering the results. If no results are returned when the filters are applied, the results will be generated without the filters.
payload
InvitePayload Specify what to share. See example for
details.FBInstant.inviteAsync({ image: base64Picture, text: { default: 'X just invaded Y\'s village!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' + '\u0642\u0631\u064A\u0629 Y!', en_US: 'X just invaded Y\'s village!', es_LA: '\u00A1X acaba de invadir el pueblo de Y!' } }, data: { myReplayData: '...' } }).then(function() { // continue with the game. });
FBInstant.inviteAsync({ image: base64Picture, text: { default: 'X just invaded Y\'s village!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' + '\u0642\u0631\u064A\u0629!', en_US: 'X just invaded Y\'s village!', es_LA: '\u00A1X acaba de invadir el pueblo de Y!' } }, cta: { default: 'Join the fight!', localizations: { ar_AR: '\u0627\u0646\u0636\u0645 \u0625\u0644\u0649' + '\u0627\u0644\u0642\u062A\u0627\u0644!', en_US: 'Join the fight!', es_LA: '\u00A1\u00DAnete a la pelea!' } }, dialogTitle: { default: 'Enlist your friends', localizations: { ar_AR: '\u062D\u0634\u062F \u0623\u0635\u062F\u0642' + '\u0627\u0621\u0643', en_US: 'Enlist your friends', es_LA: 'Alistar a tus amigos' } }, filters: ['NEW_CONTEXT_ONLY', 'EXISTING_PLAYERS_ONLY'], sections: [ {sectionType: 'GROUPS', maxResults: 2}, {sectionType: 'USERS'} ], data: { myReplayData: '...' } }).then(function() { // continue with the game. });
Returns Promise A promise that resolves when the share is completed or cancelled.
This registers a callback function that will get called when the user attempts to capture a screenshot of the game. Through the callback, the game can pass an image along with metadata that associates the screenshot. Users will then have the option to share the screenshot, or save it to their library.
provider
ScreenshotProvider FBInstant.registerScreenshotProvider(function (submitAsync) { submitAsync({ image: myBase64Image, text: 'my awesome screenshot', data: { custom_field: 'my awesome data' } }).then(function () { resumeGame(); }).catch(function (error) { log(error); }); });
Returns void
This invokes a dialog to let the user share specified content, as a post on the user's timeline, for example. A blob of data can be attached to the share which every game session launched from the share will be able to access from FBInstant.getEntryPointData(). This data must be less than or equal to 1000 characters when stringified. The user may choose to cancel the share action and close the dialog, and the returned promise will resolve when the dialog is closed regardless if the user actually shared the content or not.
payload
SharePayload Specify what to share. See example for
details.FBInstant.shareAsync({ image: base64Picture, text: 'X is asking for your help!', data: { myReplayData: '...' }, shareDestination: ['NEWSFEED', 'GROUP', 'COPY_LINK', 'MESSENGER'] switchContext: false, }).then(function() { // continue with the game. });
Returns Promise A promise that resolves when the share is completed or cancelled.
This invokes a dialog that contains a custom game link that users can copy to their clipboard, or share. A blob of data can be attached to the custom link - game sessions initiated from the link will be able to access the data through FBInstant.getEntryPointData(). This data should be less than or equal to 1000 characters when stringified. The provided text and image will be used to generate the link preview, with the game name as the title of the preview. The text is recommended to be less than 44 characters. The image is recommended to either be a square or of the aspect ratio 1.91:1. The returned promise will resolve when the dialog is closed regardless if the user actually shared the link or not.
payload
LinkSharePayload Specify the payload for the custom link. See example for
details.FBInstant.shareLinkAsync({ image: base64Picture, text: 'Come check out what Joe has built!', data: { customData: '...' }, }).then(function() { // continue with the game. });
Returns Promise A promise that resolves when the share is completed or cancelled.
Informs Facebook of an update that occurred in the game. This will temporarily yield control to Facebook and Facebook will decide what to do based on what the update is. The returned promise will resolve/reject when Facebook returns control to the game.
payload
UpdatePayload A payload that describes the update.// This will post a custom update. When people launch the game from this // message, those game sessions will be able to access the specified blob // of data through FBInstant.getEntryPointData(). FBInstant.updateAsync({ action: 'CUSTOM', cta: 'Join The Fight', image: base64Picture, text: { default: 'X just invaded Y\'s village!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' + '\u0642\u0631\u064A\u0629 Y!', en_US: 'X just invaded Y\'s village!', es_LA: '\u00A1X acaba de invadir el pueblo de Y!', } } template: 'VILLAGE_INVASION', data: { myReplayData: '...' }, strategy: 'IMMEDIATE', notification: 'NO_PUSH', }).then(function() { // closes the game after the update is posted. FBInstant.quit(); });
Returns Promise A promise that resolves when Facebook gives control back to the game.
Request that the client switch to a different Instant Game. The API will reject if the switch fails - else, the client will load the new game.
appID
string The Application ID of the Instant Game to switch to.
The application must be an Instant Game, and must belong to the same
business as the current game. To associate different games with the same
business, you can use Business Manager:
https://developers.facebook.com/docs/apps/business-manager#update-business.data
Object? An optional data payload. This will be set as the
entrypoint data for the game being switched to. Must be less than or
equal to 1000 characters when stringified.FBInstant.switchGameAsync('12345678').catch(function (e) { // Handle game change failure });
FBInstant.switchGameAsync( '12345678', {referrer: 'game_switch', reward_coins: 30}, ).catch(function (e) { // Handle game change failure });
Returns Promise
Utility function to check if the current player can call switchNativeGameAsync()
Returns Promise<boolean> if the player can call switchNativeGameAsync
Request that the client switch to its Native (Android/iOS) Game. The API will reject if the switch fails - else, the client will open the Game or Store.
data
Object? An optional data payload. This will be set as the
entrypoint data for the game being switched to. Must be less than or
equal to 1000 characters when stringified.Returns Promise
Returns whether or not the user is eligible to have shortcut creation requested.
Will return false if createShortcutAsync was already called this session or the user is ineligible for shortcut creation.
FBInstant.canCreateShortcutAsync() .then(function(canCreateShortcut) { if (canCreateShortcut) { FBInstant.createShortcutAsync() .then(function() { // Shortcut created }) .catch(function() { // Shortcut not created }); } });
Returns Promise<boolean> Promise that resolves with true if the game can request the player create a shortcut to the game, and false otherwise
Prompts the user to create a shortcut to the game if they are eligible to Can only be called once per session. (see canCreateShortcutAsync)
FBInstant.canCreateShortcutAsync() .then(function(canCreateShortcut) { if (canCreateShortcut) { FBInstant.createShortcutAsync() .then(function() { // Shortcut created }) .catch(function() { // Shortcut not created }); } });
Returns Promise
Quits the game.
FBInstant.quit();
Returns void
Log an app event and this can be tracked on Events Manager.
eventName
string Name of the event. Must be 2 to 40 characters,
and can only contain '_', '-', ' ', and alphanumeric characters.valueToSum
number An optional numeric value that FB Analytics can
calculate a sum with.parameters
Object An optional object that can contain up to
25 key-value pairs to be logged with the event. Keys must be 2 to 40
characters, and can only contain '_', '-', ' ', and alphanumeric
characters. Values must be less than 100 characters in length.var logged = FBInstant.logEvent( 'my_custom_event', 42, {custom_property: 'custom_value'} );
Returns APIError? The error if the event failed to log; otherwise returns null.
Set a callback to be fired when a pause event is triggered.
func
Function A function to call when a pause event occurs.FBInstant.onPause(function() { console.log('Pause event was triggered!'); pauseGameplay(); })
Returns void
Attempt to load or re-load a banner ad.
placementID
string The placement ID that's been set up in your
Audience Network settings.bannerPosition
string An optional parameter that sets the position of the banner to be "top" or "bottom." The default is a banner at the bottom of the screen.FBInstant.loadBannerAdAsync( 'my_placement_id' ).then(() => { console.log('success'); });
FBInstant.loadBannerAdAsync( 'my_placement_id', 'top' ).then(() => { console.log('success'); });
Returns Promise A promise that resolves after loading a banner ad, or rejects with a APIError if it couldn't be created.
Attemp to hide a banner ad.
FBInstant.hideBannerAdAsync();
Returns Promise A promise that resolves after the ad is hidden.
Attempt to create an instance of interstitial ad. This instance can then be preloaded and presented.
placementID
string The placement ID that's been setup in your
Audience Network settings.FBInstant.getInterstitialAdAsync( 'my_placement_id' ).then(function(interstitial) { interstitial.getPlacementID(); // 'my_placement_id' });
Returns Promise A promise that resolves with a AdInstance, or rejects with a APIError if it couldn't be created.
Attempt to create an instance of rewarded video. This instance can then be preloaded and presented.
placementID
string The placement ID that's been setup in your
Audience Network settings.FBInstant.getRewardedVideoAsync( 'my_placement_id' ).then(function(rewardedVideo) { rewardedVideo.getPlacementID(); // 'my_placement_id' });
Returns Promise A promise that resolves with a AdInstance, or rejects with a APIError if it couldn't be created.
Attempt to create an instance of rewarded interstitial. This instance can then be preloaded and presented.
placementID
string The placement ID that's been setup in your
Audience Network settings.FBInstant.getRewardedInterstitialAsync( 'my_placement_id' ).then(function(rewardedInterstitial) { rewardedInterstitial.getPlacementID(); // 'my_placement_id' });
Returns Promise A promise that resolves with a AdInstance, or rejects with a APIError if it couldn't be created.
Attempts to match the current player with other users looking for people to play with. There are two matching mechanisms: 1. Synchronous (realtime) match: Matches the current player with other users looking for people to play with. If successful, a new Messenger group thread will be created containing the matched players and the player will be switched into that thread's context. This will resolve when the player has successfully switched into the newly matched context. 2. Asynchronous (offline) match: Player starting an offline match will be added to a group thread right away. Players can leave the game while waiting more players to join. Once matched with other players, the player will be switched into the matched thread's context. This will resolve when the player has been successfully added to the group thread and switched into the matched context.
The default minimum and maximum number of players in one matched thread are 2 and 20 respectively, depending on how many players are trying to get matched around the same time. The values can be changed in fbapp-config.json. See the [Bundle Config documentation]https://developers.facebook.com/docs/games/instant-games/bundle-config for documentation about fbapp-config.json.
matchTag
string? Optional extra information about the player used
to group them with similar players. Players will only be grouped with
other players with exactly the same tag. The tag must only include
letters, numbers, and underscores and be 100 characters or less in
length.switchContextWhenMatched
boolean Optional extra parameter that
specifies whether the player should be immediately switched to the new
context when a match is found. By default this will be false which will
mean the player needs explicitly press play after being matched to
switch to the new context.offlineMatch
boolean Optional extra parameter that specifies
whether to start a match asynchronously. By default this will be false which
means the game will start a match synchronously.FBInstant .matchPlayerAsync('level1') .then(function() { console.log(FBInstant.context.getID()); // 12345 });
FBInstant .matchPlayerAsync() .then(function() { console.log(FBInstant.context.getID()); // 3456 });
FBInstant .matchPlayerAsync(null, true) .then(function() { console.log(FBInstant.context.getID()); // 3456 });
Returns Promise A promise that resolves when the player has been added to a group thread and switched into the thread's context.
Checks if the current player is eligible for the matchPlayerAsync API.
FBInstant .checkCanPlayerMatchAsync() .then(canMatch => { if (canMatch) { FBInstant.matchPlayerAsync('level1'); } });
Returns Promise<boolean> A promise that resolves with true if the player is eligible to match with other players and false otherwise.
Fetch a specific leaderboard belonging to this Instant Game.
name
string The name of the leaderboard. Each leaderboard for an
Instant Game must have its own distinct name.FBInstant.getLeaderboardAsync('my_awesome_leaderboard') .then(leaderboard => { console.log(leaderboard.getName()); // 'my_awesome_leaderboard' });
Returns Promise<Leaderboard> A promise that resolves with the matching leaderboard, rejecting if one is not found.
Posts a player's score to Facebook. This API should only be called at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be consistent and comparable across game sessions. For example, if Player A achieves 200 points in a session, and Player B achieves 320 points in a session, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.
score
number An integer value representing the player's score at
the end of an activity.function onScore(score) { if (score > bestSessionScore) { bestSessionScore = score; FBInstant.postSessionScore(bestSessionScore); } }
Returns void
Posts a player's score to Facebook and resolves when score has been posted. This API should only be called at the end of an activity (example: when the player doesn't have "lives" to continue the game). This API will be rate-limited when called too frequently. Scores posted using this API should be consistent and comparable across game sessions. For example, if Player A achieves 200 points in a session, and Player B achieves 320 points in a session, those two scores should be generated from activities where the scores are fair to be compared and ranked against each other.
score
number An integer value representing the player's score at
the end of an activity.function onScore(score) { if (score > bestSessionScore) { bestSessionScore = score; FBInstant.postSessionScoreAsync(bestSessionScore) .then(() => { ... }); } }
Returns Promise A promise that resolves when all platform behavior (such as dialogs) generated from the posted score has completed, and the game should resume. If the behavior resulted in a social context change, that will be reflected by the time the Promise resolves.
Fetch the instant tournament out of the current context the user is playing. This will reject if there is no instant tournament link to the current context. The instant tournament returned can be either active or expired (An instant tournament is expired if its end time is in the past). For each instant tournament, there is only one unique context ID linked to it, and that ID doesn't change.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getContextID()); console.log(tournament.getEndTime()); });
Returns Promise<Tournament>
Requests and performs haptic feedback on supported devices.
FBInstant.performHapticFeedbackAsync();
Returns Promise haptic feedback requested successfully
Copied from PromiseDone and removed a bunch of unnecessary stuff
Calls onFulfill
or onReject
, depending on the resolution of the given
promise, and intercepts any unhandled errors thrown by them.
promise
Promise onFulfill
(null | void | function (value: R): any) onReject
(null | void | function (error: any): any) Returns void
Represents a mapping from locales to translations of a given string. Each property is an optional five-character Facebook locale code of the form xx_XX. See https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml for a complete list of supported locale codes.
Type: Object
Represents app-scoped user id of current player along with a signature to verify that it indeed comes from Facebook.
data
SignedASIDData Get the app-scoped user id of the player.
FBInstant.player.getSignedASIDAsync() .then(function (result) { result.getASID(); });
Returns string The ID of the player
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 4 steps:
Signature validation should only happen on your server. Never do it on the client side as it will compromise your app secret key.
FBInstant.player.getSignedASIDAsync() .then(function (result) { result.getSignature(); // Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ });
Returns string The signature string.
The answer field is true if the current context size is between the minSize and maxSize values that are specified in the object, and false otherwise.
Type: {answer: boolean, minSize: number?, maxSize: number?}
The layer in which the video will be rendered, relative to the game.
Type: ("BACK"
| "FRONT"
)
BACK
string The video layer behind the game layerFRONT
string The video layer in front of the game layerRepresents information about a player who is connected to the current player.
player
PlayerData Get the id of the connected player.
Returns string The ID of the connected player
Get the player's display name.
Returns string? The player's display name
Get the player's public profile photo.
Returns string? A url to the player's public profile photo
An API Error returned by the Instant Games SDK
args
APIErrorArgs The relevant error code
Type: ErrorCodeType
A message describing the error
Type: string
Represents information about the player along with a signature to verify that it indeed comes from Facebook.
data
SignedPlayerInfoData Get the id of the player.
FBInstant.player.getSignedPlayerInfoAsync() .then(function (result) { result.getPlayerID(); // same value as FBInstant.player.getID() });
Returns string The ID of the player
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 4 steps:
Signature validation should only happen on your server. Never do it on the client side as it will compromise your app secret key.
FBInstant.player.getSignedPlayerInfoAsync() .then(function (result) { result.getSignature(); // Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ });
Returns string The signature string.
Represents information about a player who is in the context that the current player is playing in.
player
PlayerData Get the id of the context player.
Returns string The ID of the context player
Get the player's localized display name.
Returns string? The player's localized display name.
Get the player's public profile photo.
Returns string? A url to the player's public profile photo
Represents an individual unlockable item's status.
Type: Object
downloaded
boolean A boolean specifies whether the player
confirmed to download the unlockable item or notRepresents screenshot content provided by the game that later on can be shared by the user.
Type: Object
image
string A base64 encoded image that is the screenshot.text
string A text message to describes the screenshot.data
Object? A blob of data to attach to the screenshot. If the
user ended up sharing this screenshot, all game sessions launched from the
share will be able to access this blob through
FBInstant.getEntryPointData().Purchase Platforms that may be returned by subscriptions API, representing the platform by which the user made the purchase
Type: string
FB
string The user made the purchase on webGOOGLE
string The user made the purchase in the Android appsAPPLE
string Not eligibleOC
string -- Not eligibleUNKNOWN
string FBInstant.payments.getPurchasesAsync() .then(function(purchases) { purchases.forEach((purchase) => console.log(purchase.purchasePlatform)); });
Represents the state of a live comment view.
Type: Object
show
boolean? Show or hide the live comment view.docked_location
LiveVideoCommentViewPlacement? The chat placement.An instant game tournament.
args
TournamentArgs The unique ID that is associated with this instant tournament.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getID()); });
Returns string
The unique context ID that is associated with this instant tournament.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getContextID()); });
Returns string
Timestamp when the instant tournament ends. If the end time is in the past, then the instant tournament is already finished and has expired.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getEndTime()); });
Returns number
Title of the tournament provided upon the creation of the tournament. This is an optional field that can be set by creating the tournament using the FBInstant.tournament.createAsync() API.
Returns null if none was provided.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getTitle()); })
Returns string?
Payload of the tournament provided upon the creation of the tournament. This is an optional field that can be set by creating the tournament using the FBInstant.tournament.createAsync() API.
Returns null if none was provided.
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getPayload()); })
Returns string?
The placement where the live video comment view will display
Type: ("TOP_LEFT"
| "TOP_CENTER"
| "TOP_RIGHT"
| "BOTTOM_LEFT"
| "BOTTOM_CENTER"
| "BOTTOM_RIGHT"
)
TOP_LEFT
string The top left of the gameTOP_CENTER
string The top center of the gameTOP_RIGHT
string The top right of the gameBOTTOM_LEFT
string The bottom left of the gameBOTTOM_CENTER
string The bottom center of the gameBOTTOM_RIGHT
string The bottom right of the gameRepresents a tournament bracket
args
ArenaArgs Returns string
Returns string
Returns number
Returns string
Returns number
Returns the context ID of the match the player is in for this arena
Returns string?
Subscription Terms that may be returned by subscriptions API, representing the billing cycle of the subscription
Type: string
WEEKLY
string The user will be charged every weekBIWEEKLY
string The user will be charged every two weeksMONTHLY
string The user will be charged every monthQUARTERLY
string The user will be charged every three monthsSEMIANNUAL
string The user will be charged every six monthsANNUAL
string The user will be charged every yearFBInstant.payments.getSubscribableCatalogAsync() .then(function(catalog) { catalog.forEach((product) => console.log(product.subscriptionTerm)); });
Represents arguments to be sent to load an AR effect in Messenger Rooms.
Type: Object
effectID
string The ID of the effect to be loaded that is registered with the gameRepresentation of a group of players playing together in a messenger thread
args
GamingSquadArgs The unique gaming squad ID.
FBInstant.squads.getAsync(contextID) .then(function(squad) { console.log(squad.getID()); });
Returns string The gaming squad ID
The gaming squad name.
FBInstant.squads.getAsync(contextID) .then(function(squad) { console.log(squad.getName()); });
Returns string The name of the squad
The URI for the gaming squad image.
FBInstant.squads.getAsync(contextID) .then(function(squad) { console.log(squad.getImage()); });
Returns string URI for gaming squad image
The unique context ID that is associated with this gaming squad.
FBInstant.squads.getAsync(id) .then(function(squad) { console.log(squad.getContextID()); });
Returns string The context ID for this gaming squad
Represents an instance of an ad.
data
AdInstanceData type
AdType Return the Audience Network placement ID of this ad instance.
Returns string
Preload the ad. The returned promise resolves when the preload completes, and rejects if it failed.
FBInstant.getInterstitialAdAsync( 'my_placement_id', ).then(function(interstitial) { return interstitial.loadAsync(); }).then(function() { // Ad loaded });
Returns Promise
Present the ad. The returned promise resolves when user finished watching the ad, and rejects if it failed to present or was closed during the ad.
var ad = null; FBInstant.getRewardedVideoAsync( 'my_placement_id', ).then(function(rewardedVideo) { ad = rewardedVideo; return ad.loadAsync(); }).then(function() { // Ad loaded return ad.showAsync(); }).then(function() { // Ad watched });
Returns Promise
Live Match status that may be returned by the Instant Games API
Type: string
PENDING
string Match hasn't started yetRUNNING
string Match has begun and is runningCONCLUDED
string Match has been ended explicitlyABANDONED
string All the participants in the call have left the matchFBInstant.getCurrentMatchAsync() .then(function(match) { match.getStatusAsync().then(status => console.log(status)); });
Represents a game's product information.
Type: Object
title
string The title of the productproductID
string The product's game-specified identifierdescription
string? The product descriptionimageURI
string? A link to the product's associated imageprice
string The price of the productpriceCurrencyCode
string The currency code for the productpriceAmount
number The numeric price of a productA Live stream.
args
LiveStreamParams Get live stream name
Returns string
Get live stream concurrent viewer count
Returns number
Get video thumbnail URL
Returns string?
Get author name
Returns string
Get author picture URL
Returns string?
Get custom payload
Returns string?
Open video player overlay
Returns Promise
Represents an unlockable item config.
Type: Object
name
string unlockable item nameFetch the dynamic SDK configuration value for a given top-level key. We prioritize the result for the current SDK version, falling back to the default config value otherwise. If no value is present for either config, this function returns null.
NOTE: Remember, these values are dynamic and subject to change - make sure that the SDK code accessing them does not enforce any assumptions about their content, and that all accesses are resilient to unexpected types (in other words, accessors should only index into values after confirming their type and presence, and ensure safe fallback behavior for unexpected results). A poorly handled config access could cause the SDK to throw an exception, taking down games across the entire platform. Be careful!
key
string Returns (any | null)
Represents information about a player who is a participant in a real-time match.
player
PlayerData Get the id of the live match player.
Returns string The ID of the live match player
Get the player's display name.
Returns string? The player's display name
Get the player's public profile photo.
Returns string? A url to the player's public profile photo
An Instant Games live match status, one of LiveMatchStatus
Type: string
A filter that may be applied to a Context Choose operation 'NEW_CONTEXT_ONLY' - Prefer to only surface contexts the game has not been played in before. 'INCLUDE_EXISTING_CHALLENGES' - Include the "Existing Challenges" section, which surfaces actively played-in contexts that the player is a part of. 'NEW_PLAYERS_ONLY' - In sections containing individuals, prefer people who have not played the game.
Type: ("NEW_CONTEXT_ONLY"
| "INCLUDE_EXISTING_CHALLENGES"
| "NEW_PLAYERS_ONLY"
)
Represents display position and dimensions of the view
Type: Object
x
number the distance the view is from the left of the game viewy
number the distance the view is from the top of the game viewwidth
number the width of the viewheight
number the height of the viewA function that will get called when user requested to capture a screenshot.
Type: Function
submitAsync
ScreenshotSubmitter A function that allows the game to
submit submit a screenshot.[IN CLOSED BETA]
Represents a game's subscribable product information.
Type: Object
subscriptionTerm
SubscriptionTerm The billing cycle of
a subscriptionRepresents the state of a video player instance.
Type: Object
mute
boolean? Mute or unmute the video. Optional and defaults to
false.show
boolean? Show or hide the video. This does not affect sound.
Optional and defaults to true.play
boolean? Play or pause the video. Optional and defaults to
true.loop
boolean? Specify whether to loop the video or not. Optional
and defaults to false.x
number? X position of the video in device pixels. This starts
at the left edge of the screen and grows to the right. Optional and
defaults to 0.y
number? Y position of the video in device pixels. This starts
at the top edge of the screen and grows to the bottom. Optional and
defaults to 0.width
number? Width of the video in device pixels. Optional and
defaults to cover full screen.height
number? Height of the video in device pixels. Optional and
defaults to cover full screen.placement
VideoPlayerPlacement? The layer in which the video will
be instantiated. Optional and defaults to application specification. If
application supports both layers, defaults to BACK.volume
number? The volume level between [0,1] of the video.
Optional and defaults to 1.0.An Instant Game leaderboard
args
LeaderboardArgs The name of the leaderboard.
FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getName()); // my_leaderboard });
Returns string
The ID of the context that the leaderboard is associated with, or null if the leaderboard is not tied to a particular context.
FBInstant.getLeaderboardAsync('contextual_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getContextID()); // 12345678 });
FBInstant.getLeaderboardAsync('global_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getContextID()); // null });
Returns (string | null)
Fetches the total number of player entries in the leaderboard.
FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntryCountAsync(); }) .then(function(count) { console.log(count); }); // 24
Returns Promise<number> A unique identifier for the player.
Updates the player's score. If the player has an existing score, the old score will only be replaced if the new score is better than it. NOTE: If the leaderboard is associated with a specific context, the game must be in that context to set a score for the player.
score
number The new score for the player. Must be a 64-bit
integer number.extraData
string Metadata to associate with the stored score.
Must be less than 2KB in size. (optional, default null
)FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.setScoreAsync(42, '{race: "elf", level: 3}'); }) .then(function(entry) { console.log(entry.getScore()); // 42 console.log(entry.getExtraData()); // '{race: "elf", level: 3}' });
Returns Promise<LeaderboardEntry> Resolves with the current leaderboard entry for the player after the update.
Retrieves the leaderboard's entry for the current player, or null if the player has not set one yet.
FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getPlayerEntryAsync(); }) .then(function(entry) { console.log(entry.getRank()); // 2 console.log(entry.getScore()); // 42 console.log(entry.getExtraData()); // '{race: "elf", level: 3}' });
Returns Promise<LeaderboardEntry>? Resolves with the current leaderboard entry for the player.
Retrieves a set of leaderboard entries, ordered by score ranking in the leaderboard.
count
number The number of entries to attempt to fetch from the
leaderboard. Defaults to 10 if not specified. Currently, up to a maximum
of 100 entries may be fetched per query.offset
number The offset from the top of the leaderboard that
entries will be fetched from.FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntriesAsync(); }) .then(function(entries) { console.log(entries.length); // 10 console.log(entries[0].getRank()); // 1 console.log(entries[0].getScore()); // 42 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getRank()); // 2 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getScore()); // 40 });
FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntriesAsync(5, 3); }) .then(function(entries) { console.log(entries.length); // 5 console.log(entries[0].getRank()); // 4 console.log(entries[0].getScore()); // 34 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getRank()); // 5 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getScore()); // 31 });
Returns Promise<Array<LeaderboardEntry>> Resolves with the leaderboard entries that match the query.
Retrieves the leaderboard score entries of the current player's connected players (including the current player), ordered by local rank within the set of connected players.
count
number The number of entries to attempt to fetch from the
leaderboard. Defaults to 10 if not specified. Currently, up to a maximum
of 100 entries may be fetched per query.offset
number The offset from the set of ordered connected player
score entries to fetch from.FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getConnectedPlayerEntriesAsync(); }) .then(function(entries) { console.log(entries.length); // 10 console.log(entries[0].getRank()); // 1 console.log(entries[0].getScore()); // 42 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getRank()); // 2 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getScore()); // 40 });
FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getConnectedPlayerEntriesAsync(5, 3); }) .then(function(entries) { console.log(entries.length); // 5 console.log(entries[0].getRank()); // 4 console.log(entries[0].getScore()); // 34 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getRank()); // 5 console.log(entries(https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String).getScore()); // 31 });
Returns Promise<Array<LeaderboardEntry>> Resolves with the leaderboard entries that match the query.
Represents an instance of live comment view.
data
LiveVideoCommentViewData Return the ID of the comment channel.
Returns string
Return the ID of the live comment view.
Returns string
Get the current state of the live comment view.
Returns Promise<LiveVideoCommentViewState>
Get the native width and height of the live comment view.
Returns Promise<LiveVideoCommentDisplayRect>
Update the state of the live comment view.
state
LiveVideoCommentViewState All fields are optional and only
the properties that are included in this object will be updated.Returns void
Destroy the live comment view.
Returns void
Represents the video instace's dimensions.
Type: Object
An instant game live match that is played in a Messenger Rooms call simultaneously by all the participants.
args
LiveMatchArgs The unique live match ID.
FBInstant.room.getCurrentMatchAsync() .then(function(match) { console.log(match.getID()); });
Returns string The live match ID
The unique context ID that is associated with this live match.
FBInstant.room.getCurrentMatchAsync() .then(function(match) { console.log(match.getContextID()); });
Returns string The context ID for this live match
The current status of the live match, for example: PENDING, ABANDONED, CONCLUDED, RUNNING.
FBInstant.room.getCurrentMatchAsync() .then(function(match) { match.getStatusAsync().then(status => console.log(status)); });
Returns Promise<LiveMatchStatusType> The status of the live match
Retrieves a list of players currently active in the match.
FBInstant.room.getCurrentMatchAsync() .then(function(match) { match.getActiveParticipantsAsync().then(activeParticipants => GameMatch.updatePlayers(activeParticipants)) });
Returns Promise<Array<LiveMatchPlayer>>
Represents the current platform that the user is playing on.
Type: ("IOS"
| "ANDROID"
| "WEB"
| "MOBILE_WEB"
)
Represents an individual purchase of a game product.
Type: Object
developerPayload
string? A developer-specified string, provided
during the purchase of the productisConsumed
boolean Whether or not the purchase has been consumedpaymentActionType
string The current status of the purchase, such
as 'charge' or 'refund'paymentID
string The identifier for the purchase transactionproductID
string The product's game-specified identifierpurchasePlatform
PurchasePlatform The platform associated
with the purchase, such as "FB" for Facebook and "GOOGLE" for Google.purchasePrice
Object Contains the local amount and currency
associated with the purchased itempurchaseTime
string Unix timestamp of when the purchase occurredpurchaseToken
string A token representing the purchase that may
be used to consume the purchasesignedRequest
SignedPurchaseRequest Server-signed encoding of the purchase
requestError codes that may be returned by the Instant Games API
Type: string
ADS_FREQUENT_LOAD
string Ads are being loaded too frequently.ADS_NO_FILL
string We were not able to serve ads to the current
user. This can happen if the user has opted out of interest-based ads on
their device, or if we do not have ad inventory to show for that user.ADS_NOT_LOADED
string Attempted to show an ad that has not
been loaded successfully.ADS_TOO_MANY_INSTANCES
string There are too many concurrent
ad instances. Load and show existing ad instances before creating new ones.ANALYTICS_POST_EXCEPTION
string The analytics API experienced a
problem while attempting to post an event.CLIENT_REQUIRES_UPDATE
string [Deprecated] - The client requires
an update to access the feature that returned this result. If this result
is returned on web, it means the feature is not supported by the web client
yet. Deprecated in favor of CLIENT_UNSUPPORTED_OPERATION in v5.0 and aboveCLIENT_UNSUPPORTED_OPERATION
string The client does not support
the current operation. This may be due to lack of support on the client
version or platform, or because the operation is not allowed for the game
or player.INVALID_OPERATION
string The requested operation is invalid
or the current game state. This may include requests that violate
limitations, such as exceeding storage thresholds, or are not available in
a certain state, such as making a context-specific request in a solo
context.INVALID_PARAM
string The parameter(s) passed to the API are
invalid. Could indicate an incorrect type, invalid number of arguments, or
a semantic issue (for example, passing an unserializable object to a
serializing function).LEADERBOARD_NOT_FOUND
string No leaderboard with the requested
name was found. Either the leaderboard does not exist yet, or the name
did not match any registered leaderboard configuration for the game.LEADERBOARD_WRONG_CONTEXT
string Attempted to write to a
leaderboard that's associated with a context other than the one the game is
currently being played in.NETWORK_FAILURE
string The client experienced an issue with a
network request. This is likely due to a transient issue, such as the
player's internet connection dropping.PAYMENTS_NOT_INITIALIZED
string The client has not completed
setting up payments or is not accepting payments API calls.PENDING_REQUEST
string Represents a rejection due an existing
request that conflicts with this one. For example, we will reject any calls
that would surface a Facebook UI when another request that depends on a
Facebook UI is pending.RATE_LIMITED
string Some APIs or operations are being called
too often. This is likely due to the game calling a particular API an
excessive amount of times in a very short period. Reducing the rate of
requests should cause this error to go away.SAME_CONTEXT
string The game attempted to perform a context
switch into the current context.UNKNOWN
string An unknown or unspecified issue occurred. This
is the default error code returned when the client does not specify a code.USER_INPUT
string The user made a choice that resulted in a
rejection. For example, if the game calls up the Context Switch dialog and
the player closes it, this error code will be included in the promise
rejection.FBInstant.startGameAsync().catch(function(e) { console.log(e); }); // {code: 'CLIENT_UNSUPPORTED_OPERATION', message: '...'}
Represents an instance of an embedded video player.
data
VideoPlayerInstanceData Return the ID of the video.
Returns string
Return the ID of the video player instance.
Returns string
Get the current state of the video player instance.
Returns Promise<VideoPlayerInstanceState>
Get the native width and height of the video player instance's video content.
Returns Promise<VideoPlayerInstanceDimension>
Update the state of the video player instance.
state
VideoPlayerInstanceState All fields are optional and only
the properties that are included in this object will be updated.Returns void
Destroy the video player instance.
Returns void
Return the number of milliseconds elapsed since the beginning of the video.
Returns number
Make the video jump to the specified timestamp.
timestamp
number Milliseconds elapsed since the beginning of the video.Returns void
Make the video jump to the end of the video, or make live videos jump to live
Returns void
An Instant Games error code, one of ErrorCode
Type: string
Represents the configurations used in creating an Instant Tournament
Type: Object
title
string? Optional text title for the tournamentforceScoreValidation
boolean? Optional boolean that specifies
if the tournament requires game server validation before a score can be
added to or updated on the leaderboard.image
string? Optional base64 encoded image that will be
associated with the tournament and included in posts sharing the tournamentsortOrder
string? Optional input for the ordering of which score
is best in the tournament. The options are 'HIGHER_IS_BETTER' or
'LOWER_IS_BETTER'. If not specified, the default is 'HIGHER_IS_BETTER'.scoreFormat
string? Optional input for the formatting of the
scores in the tournament leaderboard. The options are 'NUMERIC' or 'TIME'.
If not specified, the default is 'NUMERIC'.endTime
number? Optional input for setting a custom end time
for the tournament. The number passed in represents a unix timestamp.
If not specified, the tournament will end one week after creation.forceScoreRangeValidation
boolean? Optional boolean that specifies
if the tournament should use score range validation. If true, then minimum and/or
maximum scores should be provided; scores falling outside the range will be automatically
rejected. If either minimum or maximum is null, then that side of the range will be ignored.minimumScore
number? Optional input will only be used if forceScoreRangeValidation is true.
If it is, scores below this will be automatically rejected. If null or forceScoreRangeValidation is false,
no minimum will be usedmaximumScore
number? Optional input will only be used if forceScoreRangeValidation is true.
If it is, scores above this will be automatically rejected. If null or forceScoreRangeValidation is false,
no maximum will be usedRepresents content to be shared in invites sent by the user.
Type: Object
image
string A base64 encoded image to be shared.text
(string | LocalizableContent) A text message, or an object
with the default text as the value of 'default' and another object
mapping locale keys to translations as the value of 'localizations'.cta
(string? | LocalizableContent?) Optional call-to-action button
text. By default we will use a localized 'Play' as the button text.
To provide localized versions of your own call to action, pass an object
with the default cta as the value of 'default' and another object
mapping locale keys to translations as the value of 'localizations'.dialogTitle
(string? | LocalizableContent?) An optional title to
display at the top of the invite dialog instead of the generic title. This
param is not sent as part of the message, but only displays in the dialog
header. The title can be either a string or an object with the default
text as the value of 'default' and another object mapping locale keys to
translations as the value of 'localizations'.data
Object? A blob of data to attach to the share. All game
sessions launched from the share will be able to access this blob through
FBInstant.getEntryPointData().filters
Array<InviteFilter>? The set of filters to apply to the
suggestions. Multiple filters may be applied. If no results are returned
when the filters are applied, the results will be generated without the
filters.sections
Array<InviteSection>? The set of sections to be
included in the dialog. Each section can be assigned a maximum number of
results to be returned (up to a maximum of 10). If no max is included, a
default max will be applied. Sections will be included in the order they
are listed in the array. The last section will include a larger maximum
number of results, and if a maxResults is provided, it will be ignored. If
this array is left empty, default sections will be used.Type: string
Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ
A filter that may be applied to an inviteAsync operation. If no results are returned with the filters, then the filters will not be applied. 'NEW_CONTEXT_ONLY' - Prefer to only surface contexts the game has not been played in before. This can include players who have not played the game before. 'NEW_PLAYERS_ONLY' - Prefer to only surface people who have not played the game before. 'EXISTING_CONTEXT_ONLY' - Prefer to only surface contexts the game has been played in before. 'EXISTING_PLAYERS_ONLY' - Prefer to only surface people who have played the game before.
Type: ("NEW_CONTEXT_ONLY"
| "NEW_PLAYERS_ONLY"
| "EXISTING_CONTEXT_ONLY"
| "EXISTING_PLAYERS_ONLY"
)
The configuration of a purchase request for a product registered to the game.
Type: Object
productID
string The identifier of the product to purchasedeveloperPayload
string? An optional developer-specified
payload, to be included in the returned purchase's signed request.Represents a section in the inviteAsync dialog that contains suggested matches. The sections will be shown in the order they are included in the array, and the last section will contain as many results as possible.
Type: Object
sectionType
InviteSectionType The type of section to include in the
inviteAsync dialogmaxResults
number? Optional maximum number of results to include
in the section. This can be no higher than 10. This will be disregarded for the last
section, which will contain as many results as possible. If not included, the default
maximum number of results for that section type will be used.Represents an AR effect object that can be shown in a Messenger Rooms call.
args
CameraEffectArgs The unique camera effect ID.
FBInstant.room.loadCameraEffectAsync() .then(function(effect) { console.log(effect.getID()); });
Returns string The camera effect ID
Represents the type of section to include. All section types may include both new and existing contexts and players.
Type: string
GROUPS
string This contains group contexts, such
as contexts from group threads.USERS
string This contains individual users, such as friends
or 1:1 threads.[IN CLOSED BETA]
Represents the purchase of a subscription.
Type: Object
deactivationTime
number? The Unix timestamp of when the
subscription entitlement will no longer be active, if subscription not
renewed or canceled. Otherwise, nullisEntitlementActive
boolean Whether or not the user is an active
subscriber and should receive entitlement to the subscription benefitsperiodStartTime
number The current start Unix timestamp of the
latest billing cycleperiodEndTime
number The current end Unix timestamp of the latest
billing cycleproductID
string The corresponding subscribable product's
game-specified identifierpurchasePlatform
PurchasePlatform The platform associated
with the purchase, such as "FB" for Facebook and "GOOGLE" for Google.purchasePrice
Object Contains the local amount and currencypurchaseTime
string Unix timestamp of when the purchase occurredpurchaseToken
Object A token representing the purchase that may
be used to consume the purchasesignedRequest
SignedPurchaseRequest Server-signed encoding of the purchase
requestsubscriptionTerm
SubscriptionTerm The billing cycle of
a subscriptionA parameter that may be applied to a shareAsync operation. This set up sharing destination in the share dialog. 'NEWSFEED' - Enable share to newsfeed option 'GROUP' - Enable share to official game group option. This is only available for games with official game group. To set up official game group, add a page in the game app setting in https://www.developers.facebook.com, and then create a group for the page in https://facebook.com. 'COPY_LINK' - Enable copy the game link in clipboard 'MESSENGER' - Enable share game to messenger option
Type: InstantGameShareDestinationType
Represents content to be shared by the user.
Type: Object
image
string A base64 encoded image to be shared.media
MediaParams? Optional content for the gif or video.text
string A text message to be shared.data
Object? A blob of data to attach to the share. All game
sessions launched from the share will be able to access this blob through
FBInstant.getEntryPointData().shareDestination
Array<ShareDestination>? A optional array to set
sharing destinations in the share dialog.If not specified all available
sharing destinations will be displayed.switchContext
boolean? A flag indicating whether to switch the user
into the new context created on sharingRepresents a custom link to be shared by the user.
Type: Object
image
string? A base64 encoded image to be shown for the link preview. The image is recommended to either be a square or of the aspect ratio 1.91:1text
string? A text description for the link preview. Recommended to be less than 44 charactersdata
Object A blob of data to associate with the shared link. All game
sessions launched from the share will be able to access this blob through
FBInstant.getEntryPointData().Specify how we could get the content for the media.
Type: {url: string}
Represents the media payload used by custom update and custom share.
Type: {gif: MediaContent?, video: MediaContent?}
Optional
MediaContent , if provided, the content should contain
information for us to get the gif.Optional
MediaContent , if provided, the content should contain
information for us to get the video.gif
MediaContent? video
MediaContent? Represents the type of the update action to perform.
Type: string
CUSTOM
string A custom update, with all content specified by
the game.LEADERBOARD
string An update associated with an Instant Game
leaderboard.Currently api calls in this module are logged with without module name. Keep the module empty module name to avoid diverging logging
Type: string
Represents content used to reshare an Instant Tournament.
Type: Object
score
number An optional integer value representing the player's
latest score.data
Object? A blob of data to attach to the update.
Must be less than or equal to 1000 characters when stringified.Represents parameters used to configure a Gaming Squad
Type: Object
name
string An optional prefill for the squad name input in the creation dialog.
The player ultimately has control over the actual name.image
string Optional base64 encoded image that will be
associated with the gaming squad and will show up in the creation dialog. It will be the profile icon for the Messenger threadsquadTerm
string Optional localized term to use in place of 'Squad' in the dialog.Represents parameters used to configure the Join dialog
Type: Object
squadTerm
string Optional localized term to use in place of 'Squad' in the dialog.Represents a custom update for FBInstant.updateAsync. Note that if localized content is not provided, a Facebook supplied localized string will be used for the call to action and text.
The default
string should always be in English.
Type: Object
action
UpdateAction For custom updates, this should be 'CUSTOM'.template
string ID of the template this custom update is using.
Templates should be predefined in fbapp-config.json. See
the [Bundle Config documentation]https://developers.facebook.com/docs/games/instant-games/bundle-config for
documentation about fbapp-config.json.cta
(string? | LocalizableContent?) Optional call-to-action button
text. By default we will use a localized 'Play' as the button text.
To provide localized versions of your own call to action, pass an object
with the default cta as the value of 'default' and another object
mapping locale keys to translations as the value of 'localizations'.image
string? Optional data URL of a base64 encoded image.media
MediaParams? Optional content for the gif or
video. At least one image or media should be provided in order to render
the update.text
(string | LocalizableContent) A text message, or an object
with the default text as the value of 'default' and another object
mapping locale keys to translations as the value of 'localizations'.data
Object? A blob of data to attach to the update. All game
sessions launched from the update will be able to access this blob through
FBInstant.getEntryPointData(). Must be less than or equal to 1000
characters when stringified.strategy
string? Specifies how the update should be
delivered. This can be one of the following:
'IMMEDIATE' - The update should be posted immediately.
'LAST' - The update should be posted when the game session ends. The most
recent update sent using the 'LAST' strategy will be the one sent.
If no strategy is specified, we default to 'IMMEDIATE'.notification
string? Specifies notification setting for the
custom update. This can be 'NO_PUSH' or 'PUSH', and defaults to 'NO_PUSH'.
Use push notification only for updates that are high-signal and immediately
actionable for the recipients. Also note that push notification is not
always guaranteed, depending on user setting and platform policies.Represents parameters used to configure the Leave dialog
Type: Object
squadTerm
string Optional localized term to use in place of 'Squad' in the dialog.Represents parameters used to configure the Add to Squad dialog
Type: Object
squadTerm
string Optional localized term to use in place of 'Squad' in the dialog.Represents a leaderboard update for FBInstant.updateAsync.
Type: Object
action
UpdateAction For a leaderboard update, this should be
'LEADERBOARD'.
text. By default we will use a localized 'Play Now' as the button text.name
string The name of the leaderboard to feature
in the update.text
string? Optional text message. If not specified, a
localized fallback message will be provided instead.Represents a string with localizations and a default value to fall back on.
Type: Object
default
string The default value of the string to use if
the viewer's locale is not a key in the localizations object.localizations
LocalizationsDict Specifies what string to use
for viewers in each locale.
See https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml
for a complete list of supported locale values.Type: (CustomUpdatePayload | LeaderboardUpdatePayload)
A score entry for an Instant Game leaderboard
args
{rank: number, score: number, format_score: string, ts: number, extra_data: string?, player: {name: string, photo: string, player_id: string}} Gets the score associated with the entry.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getScore()); // 9001 });
Returns number Returns an integer score value.
Gets the score associated with the entry, formatted with the score format associated with the leaderboard.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getFormattedScore()); // '90.01 meters' });
Returns string Returns a formatted score.
Gets the timestamp of when the leaderboard entry was last updated.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getTimestamp()); // 1515806355 });
Returns number Returns a Unix timestamp.
Gets the rank of the player's score in the leaderboard.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getRank()); // 2 });
Returns number Returns the entry's leaderboard ranking.
Gets the developer-specified payload associated with the score, or null if one was not set.
leaderboard.setScoreAsync(42, '{race: "elf", level: 3}'); .then(function(entry) { console.log(entry.getExtraData()); // '{race: "elf", level: 3}' });
Returns string? An optional developer-specified payload associated with the score.
Gets information about the player associated with the entry.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getName()); // Sally });
Returns LeaderboardPlayer
Details about the player associated with a score entry.
Gets the player's localized display name.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getName()); // Sally });
Returns string The player's localized display name.
Returns a url to the player's public profile photo.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getPhoto()); // <photo_url> });
Returns string? Url to the player's public profile photo.
Gets the game's unique identifier for the player.
leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getID()); // 12345678 });
Returns string? The game-scoped identifier for the player.