Instant Games SDK v8.0 (Network Enabled Zero Permissions)
Updated: Jul 17, 2026
Copy for LLM
Changelog
FBInstant.overlayViewsNew module added for creation and management of overlay view iFrames to be used for Zero Permissions.- Removal of
FBInstant.player.getName()andFBInstant.player.getPhoto(). Profile pictures and player names APIs have been removed to fit the Zero Permissions model. You can use overlay views to render this information instead. - Added
FBInstant.openExternalLinkAsync(url)for opening approved external URLs after platform confirmation. - Added
FBInstant.player.getAssociatedAppsASIDAsync()for retrieving ASIDs for linked associated apps. See Cross-play Management for more information - Added
FBInstant.player.getSignedAssociatedAppsASIDAsync()for retrieving signed ASIDs for linked associated apps. - Added
FBInstant.player.createNEZPNotificationContentAsync()for creating NEZP notification content. - Added
FBInstant.player.getAgeCategoryAsync()for retrieving the player’s age category. - Added
destroyAsync()toFBInstant.overlayViewsfor destroying an overlay view.
API overview
Version
8.0 exposes the root FBInstant object together with namespace-style sub-objects for major feature areas. Use this page for root FBInstant APIs, or jump directly to a namespace page for focused documentation.| API surface | Description |
|---|---|
Core SDK methods for initialization, platform information, lifecycle, sharing, ads, entry points, haptics, session state, and shortcuts. | |
Official page and group actions for community growth surfaces. | |
Context identification, creation, and player retrieval for multiplayer and social sessions. | |
Overlay view creation, management, and event handling APIs. | |
Product catalog, purchase, consumption, and payments readiness APIs. | |
Player identity, signed identifiers, bot subscription, data storage, and connected-player APIs. | |
Room metadata and current match accessors. | |
Tournament score posting, creation, discovery, sharing, and join flows. |
Namespaced APIs are documented only on their dedicated pages listed above.
Supporting object types such as
AdInstance, OverlayView, Product, Purchase, SignedASID, SignedAssociatedAppASID, Tournament, and ContextPlayer are documented in the sections where they are returned or consumed.FBInstant (Core)
Currently api calls in this module are logged with without module name.
getLocale()
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.
Returns:
string — The current locale.Example:
// This function should be called after FBInstant.initializeAsync() // resolves. var locale = FBInstant.getLocale(); // 'en_US'
getPlatform()
The platform on which the game is currently running. The value will always
be null until FBInstant.initializeAsync() resolves.
Returns:
?Platform — The platform on which the game is running.Example:
// This function should be called after FBInstant.initializeAsync() // resolves. var platform = FBInstant.getPlatform(); // 'IOS'
getSDKVersion()
The string representation of this SDK version.
Returns:
string — The SDK version.Example:
// This function should be called after FBInstant.initializeAsync() // resolves. var sdkVersion = FBInstant.getSDKVersion(); // '2.0'
initializeAsync()
Initializes the SDK library. This should be called before any other SDK
functions.
Returns:
Promise — A promise that resolves when the SDK is ready to use.Throws:
INVALID_OPERATION
Example:
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(); });
inviteAsync()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
payload | InviteWithOverlayPayload | Specify what to share. See example for details. |
Returns:
Promise<void> — A promise that resolves when the share is completed or cancelled.Throws:
INVALID_PARAMNETWORK_FAILUREPENDING_REQUESTCLIENT_UNSUPPORTED_OPERATIONINVALID_OPERATION
Example:
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!' } }, notificationText: { default: 'X just performed B action, play now!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A' } }, 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. });
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
payload | ShareWithOverlayPayload | Specify what to share. See example for details. |
Returns:
Promise<void> — A promise that resolves when the share is completed or cancelled.Throws:
INVALID_PARAMNETWORK_FAILUREPENDING_REQUESTCLIENT_UNSUPPORTED_OPERATIONINVALID_OPERATION
Example:
FBInstant.shareAsync({ intent: 'REQUEST', 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. });
openExternalLinkAsync()
Opens an approved external destination after the platform confirms with the
player and attempts to open it. The URL must be an absolute
http:// or
https:// URL. Availability depends on the current client and platform, so
you should check FBInstant.getSupportedAPIs() before calling this API.Parameters:
| Parameter | Type | Description |
|---|---|---|
url | string | The absolute external destination to open. |
Returns:
Promise<void> — A promise that resolves after the platform
confirms and attempts to open the external link, and rejects if the user
cancels, the destination is invalid, or the client definitively fails to
dispatch the open request.Throws:
INVALID_PARAMPENDING_REQUESTINVALID_OPERATION
Example:
if (FBInstant.getSupportedAPIs().includes('openExternalLinkAsync')) { FBInstant.openExternalLinkAsync('https://example.com/help') .then(function() { // continue after the platform attempts to open the link. }) .catch(function(error) { console.log(error.code, error.message); }); }
postSessionScore()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
score | number | An integer value representing the player’s score at the end of an activity. |
Returns:
voidExample:
function onScore(score) { if (score > bestSessionScore) { bestSessionScore = score; FBInstant.postSessionScore(bestSessionScore); } }
postSessionScoreAsync()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
score | number | An integer value representing the player’s score at the end of an activity. |
Returns:
Promise<void> — 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.Example:
function onScore(score) { if (score > bestSessionScore) { bestSessionScore = score; FBInstant.postSessionScoreAsync(bestSessionScore) .then(() => { ... }); } }
performHapticFeedbackAsync()
Requests and performs haptic feedback on supported devices.
Returns:
Promise<void> — haptic feedback requested successfullyThrows:
CLIENT_UNSUPPORTED_OPERATIONINVALID_OPERATION
Example:
FBInstant.performHapticFeedbackAsync();
updateAsync()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
payload | A payload that describes the update. |
Returns:
Promise<void> — A promise that resolves when Facebook gives control back to the game.Throws:
INVALID_PARAMPENDING_REQUESTINVALID_OPERATION
Example:
// 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!', } } notificationText: { default: 'X just performed B action, play now!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A' } } template: 'VILLAGE_INVASION', data: { myReplayData: '...' }, strategy: 'IMMEDIATE', notification: 'NO_PUSH', }).then(function() { // closes the game after the update is posted. FBInstant.quit(); });
switchGameAsync()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
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(optional) | 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<void> — A promise that resolves when the game switch is successful.Throws:
USER_INPUTINVALID_PARAMPENDING_REQUESTCLIENT_REQUIRES_UPDATE
Example:
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 });
canCreateShortcutAsync()
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.
Returns:
Promise<boolean> — Promise that resolves with true if the game can request the player create a shortcut to the game, and false otherwiseThrows:
PENDING_REQUESTCLIENT_REQUIRES_UPDATEINVALID_OPERATION
Example:
FBInstant.canCreateShortcutAsync() .then(function(canCreateShortcut) { if (canCreateShortcut) { FBInstant.createShortcutAsync() .then(function() { // Shortcut created }) .catch(function() { // Shortcut not created }); } });
createShortcutAsync()
Prompts the user to create a shortcut to the game if they are eligible to
Can only be called once per session.
(see
canCreateShortcutAsync)Returns:
Promise<void> — A promise that resolves when the shortcut is created, or rejects if creation fails.Throws:
USER_INPUTPENDING_REQUESTCLIENT_REQUIRES_UPDATEINVALID_OPERATION
Example:
FBInstant.canCreateShortcutAsync() .then(function(canCreateShortcut) { if (canCreateShortcut) { FBInstant.createShortcutAsync() .then(function() { // Shortcut created }) .catch(function() { // Shortcut not created }); } });
setLoadingProgress()
Report the game’s initial loading progress.
Parameters:
| Parameter | Type | Description |
|---|---|---|
percentage | number | A number between 0 and 100. |
Returns:
voidExample:
FBInstant.setLoadingProgress(50); // Assets are 50% loaded
getSupportedAPIs()
Provides a list of API functions that are supported by the client.
Returns:
Array<string> — List of API functions that the client explicitly supports.Example:
// This function should be called after FBInstant.initializeAsync() // resolves. FBInstant.getSupportedAPIs(); // ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...]
getEntryPointData()
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.
Returns:
?Object — Data associated with the current entry point.Example:
// This function should be called after FBInstant.initializeAsync() // resolves. const entryPointData = FBInstant.getEntryPointData();
getEntryPointAsync()
Returns the entry point that the game was launched from.
This function should not be called until FBInstant.startGameAsync has
resolved.
Returns:
Promise<string> — The name of the entry point from which the user started the gameExample:
// This function should be called after FBInstant.initializeAsync() // resolves. FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint)); // 'admin_message'
setSessionData()
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.
Parameters:
| Parameter | Type | Description |
|---|---|---|
sessionData | Object | An arbitrary data object, which must be less than or equal to 1000 characters when stringified. |
Returns:
voidExample:
FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]});
startGameAsync()
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.
Returns:
Promise — A promise that resolves when the game should start.Throws:
INVALID_PARAMCLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.startGameAsync().then(function() { myGame.start(); });
quit()
Quits the game.
Returns:
voidExample:
FBInstant.quit();
logEvent()
Log an app event with Facebook Analytics. Use this to track custom in-game events such as level completions, purchases, or player actions.
Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
|
eventName | string | Name of the event. Must be 2 to 40 characters, and can only contain _, -, ` , and alphanumeric characters. |
| valueToSum | number _(optional)_ | An optional numeric value that Facebook Analytics can calculate a sum with. |
| parameters | Object _(optional)_ | 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. |Returns:
?APIError — Returns null if the event was logged successfully, or an APIError if it failed to log.Throws:
ANALYTICS_POST_EXCEPTION
Example:
var logged = FBInstant.logEvent( 'my_custom_event', 42, {custom_property: 'custom_value'} );
onPause()
Set a callback to be fired when a pause event is triggered (when the user switches away from the window/tab on desktop or when the user switches apps on mobile).
Parameters:
| Parameter | Type | Description |
|---|---|---|
func | Function | A function to call when a pause event occurs. |
Returns:
voidExample:
FBInstant.onPause(function() { console.log('Pause event was triggered!'); pauseGameplay(); })
onResume()
Set a callback to be fired when a resume event is triggered (when the user switches back to the game window/tab on desktop or when the user switches back to the app on mobile).
Parameters:
| Parameter | Type | Description |
|---|---|---|
func | Function | A function to call when a resume event occurs. |
Returns:
voidExample:
FBInstant.onResume(function() { console.log('Resume event was triggered!'); resumeGameplay(); })
onContextChange()
Set a callback to be fired when the game context changes. This can happen when a user
joins or leaves a session, or when the player switches to a different context.
Parameters:
| Parameter | Type | Description |
|---|---|---|
onSuccess | EventHandler | A function to call when the context changes successfully. The function will receive the new context ID as a parameter. |
onError | EventHandler | A function to call when an error occurs during context change. The function will receive an error object as a parameter. |
Returns:
voidExample:
FBInstant.onContextChange( function(contextID) { console.log('Context changed to: ' + contextID); updateGameUI(); }, function(error) { console.error('Context change error: ' + error); } );
Types
Platform
Represents the current platform that the user is playing on.
EndGamePayload
Class for formatting end game payloads for custom updates
CustomUpdateWithOverlayPayload
The payload object passed to
updateAsync() to describe a custom update. At least one of image, imageOverlayPath, or media must be provided.Properties:
| Property | Type | Description |
|---|---|---|
action | 'CUSTOM' | Must be 'CUSTOM' for custom updates. |
template | string | ID of the template this custom update is using. Templates should be predefined in fbapp-config.json. See Bundle Config. |
text | string | LocalizableContent | The text message for the update. To provide localized versions, pass a LocalizableContent object. Supports template tokens for user data and developer parameters. |
cta | string | LocalizableContent(optional) | Call-to-action button text. Defaults to a localized “Play” if not specified. |
image | string(optional) | Data URL of a base64 encoded image. Required if imageOverlayPath and media are not specified. |
imageOverlayPath | string(optional) | Path to an overlay view XML file that defines the image to share. Required if image and media are not specified. |
pathToCSS | string(optional) | Path to a CSS file used for styling the overlay view XML. Required if className is used in the imageOverlayPath XML. |
initialData | Object(optional) | Data passed to the overlay view XML for template rendering. Required if the text or overlay XML uses developer-defined parameters. |
media | MediaParams(optional) | Content for a GIF or video. Required if image and imageOverlayPath are not specified. |
notificationText | string | LocalizableContent(optional) | Notification text separate from the message text. If not provided, the text value is used for both the Messenger message and the notification. |
data | Object(optional) | Data attached to the update. Game sessions launched from this update can access it via FBInstant.getEntryPointData(). Must be less than or equal to 1000 characters when stringified. |
strategy | string(optional) | How the update is delivered. 'IMMEDIATE' posts immediately (default). 'LAST' posts when the game session ends (most recent wins). 'IMMEDIATE_CLEAR' posts immediately and clears any pending updates. |
notification | string(optional) | Push notification behavior. 'NO_PUSH' (default) does not send a push notification. 'PUSH' sends a push notification (not guaranteed depending on user settings and platform policies). |
LocalizableContent
An object for providing localized text strings.
Properties:
| Property | Type | Description |
|---|---|---|
default | string | The default text string used as a fallback. |
localizations | Object | An object mapping locale codes (for example, en_US, es_LA, ar_AR) to translated strings. |
MediaParams
Content for GIF or video media in custom updates.
Properties:
| Property | Type | Description |
|---|---|---|
gif | MediaContent(optional) | A GIF to include in the update. |
video | MediaContent(optional) | A video to include in the update. |
MediaContent has the following shape:| Property | Type | Description |
|---|---|---|
url | string | The URL of the media content. |
ErrorCode
Error codes that may be returned by the Instant Games API
Properties:
| Property | Type | Description |
|---|---|---|
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 above |
CLIENT_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. |
OPERATION_SUPPRESSED | string | - The operation was suppressed by the platform. This may be due to user-level rate limiting, play style restrictions, or other reasons. |
GLOBAL_LEADERBOARD_NOT_FOUND | string | - No global leaderboard with the requested ID was found. Either the leaderboard does not exist yet, or the ID did not match any registered leaderboard, you can verify the leaderboard ID in the Global Leaderboard section of the Instant Games Dashboard. |
IARC_CERT_NOT_FOUND | string | - The requested IARC (International Age Rating Coalition) certificate was not found. |
IARC_CERT_TEST_ONLY | string | - This is a test IARC (International Age Rating Coalition) operation. |
IARC_SUBMIT_CERT_FAILED | string | - Thw IARC (International Age Rating Coalition) certificate failed to be submitted. |
IARC_SUBMIT_EMAIL_FAILED | string | - The developer’s IARC (International Age Rating Coalition) contact email failed to be submitted. |
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. |
MOCK_IAP | string | - User is temporarily turning off Mock IAP and switching to production flow for current purchase |
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. |
TOURNAMENT_NOT_SHAREABLE | string | - The game attempted to share a private tournament. This is only possible for non-private tournaments. If a score was submitted with the share call, then the score was still submitted. |
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. |
ErrorCodeType
An Instant Games error code, one of
ErrorCodeAPIErrorArgs
Arguments for creating an API Error.
Properties:
| Property | Type | Description |
|---|---|---|
code | ErrorCodeType(optional) | - The error code. Defaults to UNKNOWN if not provided. |
message | string | - A message describing the error. |
extraData | string(optional) | - Optional extra data for logging purposes. |
APIError
An API Error returned by the Instant Games SDK
Properties:
| Property | Type | Description |
|---|---|---|
code | - The relevant error code | |
message | string | - A message describing the error |
extraData | string(optional) | - Optional extra data for logging purposes |
Ads
Deprecated: Banner ads will be deprecated in 31 March 2027. Plan to migrate to alternative ad formats before then. Find out more about the deprecation here
Attempt to load and display a banner ad. The banner is shown at the specified position on screen. Only one banner ad can be displayed at a time; calling this again replaces the current banner.
Parameters:
| Parameter | Type | Description |
|---|---|---|
placementID | string | The placement ID that’s been set up in your Audience Network settings. |
bannerPosition | string(optional) | The position of the banner on screen. Valid values are "top" or "bottom". Defaults to "bottom". |
Returns:
Promise<void> — A promise that resolves after loading a banner ad, or rejects with an APIError if it couldn’t be created.Throws:
RATE_LIMITEDINVALID_PARAMCLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.loadBannerAdAsync('my_placement_id', 'bottom') .then(function() { console.log('Banner ad loaded and displayed'); }) .catch(function(error) { console.error('Failed to load banner ad:', error.code, error.message); });
Deprecated: Banner ads will be deprecated in 31 March 2027. Plan to migrate to alternative ad formats before then. Find out more about the deprecation here
Attempt to hide the currently displayed banner ad.
Returns:
Promise<void> — A promise that resolves after the ad is hidden.Throws:
CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.hideBannerAdAsync();
getInterstitialAdAsync()
Attempt to create an instance of interstitial ad. This instance can then be
preloaded and presented.
Parameters:
| Parameter | Type | Description |
|---|---|---|
placementID | string | The placement ID that’s been setup in your Audience Network settings. |
Returns:
Promise<AdInstance> — A promise that resolves with a AdInstance, or rejects with a APIError if it couldn’t be created.Throws:
ADS_TOO_MANY_INSTANCESCLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.getInterstitialAdAsync( 'my_placement_id' ).then(function(interstitial) { interstitial.getPlacementID(); // 'my_placement_id' });
getRewardedVideoAsync()
Attempt to create an instance of rewarded video. This instance can then be
preloaded and presented.
Parameters:
| Parameter | Type | Description |
|---|---|---|
placementID | string | The placement ID that’s been setup in your Audience Network settings. |
Returns:
Promise<AdInstance> — A promise that resolves with a AdInstance, or rejects with a APIError if it couldn’t be created.Throws:
ADS_TOO_MANY_INSTANCESCLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.getRewardedVideoAsync( 'my_placement_id' ).then(function(rewardedVideo) { rewardedVideo.getPlacementID(); // 'my_placement_id' });
Types
AdInstanceData
Data structure representing an ad instance.
Properties:
| Property | Type | Description |
|---|---|---|
adInstanceID | string | - Unique identifier for the ad instance |
placementID | string | - Audience Network placement ID for the ad |
AdInstance
constructor()
Creates a new AdInstance.
Parameters:
| Parameter | Type | Description |
|---|---|---|
data | - The data for this ad instance | |
type | AdType | - The type of ad (interstitial, rewarded video, etc.) |
getPlacementID()
Returns the Audience Network placement ID of this ad instance.
Returns:
string — The placement ID for this adloadAsync()
Preload the ad. The returned promise resolves when the preload
completes, and rejects if it failed.
Returns:
Promise<void> — A promise that resolves when the ad is successfully preloadedThrows:
ADS_FREQUENT_LOADADS_NO_FILLINVALID_PARAMNETWORK_FAILURE
Example:
FBInstant.getInterstitialAdAsync( 'my_placement_id', ).then(function(interstitial) { return interstitial.loadAsync(); }).then(function() { // Ad loaded });
showAsync()
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.
Returns:
Promise<void> — A promise that resolves when the user has finished watching the adThrows:
ADS_NOT_LOADEDINVALID_PARAMNETWORK_FAILUREINVALID_OPERATIONRATE_LIMITEDUSER_INPUT
Example:
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 });
getEndTime()
Timestamp when the instant tournament ends. If the end time is in the past,
then the instant tournament is already finished and has expired.
Returns:
number — Unix timestamp when the tournament ends.Example:
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getEndTime()); });
getTournamentType()
Type of the tournament, eg default, page_hosted, daily, etc.
Returns:
InstantGameTimedLeaderboardTournamentExternalType — The type of tournament.Example:
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getTournamentType()); });
getTitle()
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.
Returns:
?string — The title of the tournament, or null if none was provided.Example:
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getTitle()); })
getPayload()
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.
Returns:
?string — The payload data of the tournament, or null if none was provided.Example:
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getPayload()); })
getVersion()
Returns the version number of the FBInstant SDK
Returns:
string — The version number as a string (e.g. “8.0”)Types
Platform
Represents the current platform that the user is playing on.
AdInstanceData
Data structure representing an ad instance.
Properties:
| Property | Type | Description |
|---|---|---|
adInstanceID | string | - Unique identifier for the ad instance |
placementID | string | - Audience Network placement ID for the ad |
AdInstance
Represents an instance of an ad.
EndGamePayload
Class for formatting end game payloads for custom updates
TournamentArgs
Arguments for creating a Tournament instance.
Properties:
| Property | Type | Description |
|---|---|---|
tournamentID | string | - The unique identifier for the tournament. |
contextID | string | - The context ID associated with the tournament. |
endTime | number | - Timestamp when the tournament ends. |
tournamentType | InstantGameTimedLeaderboardTournamentExternalType | - The type of tournament. |
title | string(optional) | - Optional title for the tournament. |
payload | string(optional) | - Optional data payload for the tournament. |
Tournament
An instant game tournament.
ErrorCode
Error codes that may be returned by the Instant Games API
Properties:
| Property | Type | Description |
|---|---|---|
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 above |
CLIENT_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. |
OPERATION_SUPPRESSED | string | - The operation was suppressed by the platform. This may be due to user-level rate limiting, play style restrictions, or other reasons. |
GLOBAL_LEADERBOARD_NOT_FOUND | string | - No global leaderboard with the requested ID was found. Either the leaderboard does not exist yet, or the ID did not match any registered leaderboard, you can verify the leaderboard ID in the Global Leaderboard section of the Instant Games Dashboard. |
IARC_CERT_NOT_FOUND | string | - The requested IARC (International Age Rating Coalition) certificate was not found. |
IARC_CERT_TEST_ONLY | string | - This is a test IARC (International Age Rating Coalition) operation. |
IARC_SUBMIT_CERT_FAILED | string | - Thw IARC (International Age Rating Coalition) certificate failed to be submitted. |
IARC_SUBMIT_EMAIL_FAILED | string | - The developer’s IARC (International Age Rating Coalition) contact email failed to be submitted. |
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. |
MOCK_IAP | string | - User is temporarily turning off Mock IAP and switching to production flow for current purchase |
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. |
TOURNAMENT_NOT_SHAREABLE | string | - The game attempted to share a private tournament. This is only possible for non-private tournaments. If a score was submitted with the share call, then the score was still submitted. |
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. |
ErrorCodeType
An Instant Games error code, one of
ErrorCodeAPIErrorArgs
Arguments for creating an API Error.
Properties:
| Property | Type | Description |
|---|---|---|
code | ErrorCodeType(optional) | - The error code. Defaults to UNKNOWN if not provided. |
message | string | - A message describing the error. |
extraData | string(optional) | - Optional extra data for logging purposes. |
APIError
An API Error returned by the Instant Games SDK
Properties:
| Property | Type | Description |
|---|---|---|
code | - The relevant error code | |
message | string | - A message describing the error |
extraData | string(optional) | - Optional extra data for logging purposes |
Matchmaking
matchPlayerAsync()
Attempts to match 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 context switched to that thread. 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 settings. After matching, the game can get the stats of the matched players in the new context by calling FBInstant.context.getPlayersAsync. This function can be called after FBInstant.startGameAsync() resolves.
Parameters:
| Parameter | Type | Description |
|---|---|---|
matchTag | ?string(optional) | Optional extra information about the player used to group players together. 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) | 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 a button to switch to the new context. |
offlineMatch | boolean(optional) | Optional extra parameter that specifies whether to match the player with others in an async manner and not participate in realtime gameplay. By default this will be false which means the player wants to play with others in realtime. |
Returns:
Promise<void> — A promise that resolves when the player has been added to a group thread and switched into the thread’s context.Throws:
INVALID_PARAMNETWORK_FAILUREUSER_INPUTPENDING_REQUESTCLIENT_UNSUPPORTED_OPERATIONINVALID_OPERATION
Example:
FBInstant.matchPlayerAsync('level1').then(function() { console.log('Player matched!'); });
checkCanPlayerMatchAsync()
Checks if the current player is eligible for the matchPlayerAsync API.
Returns:
Promise<boolean> — A promise that resolves with true if the player is eligible to match with other players and false otherwise.Throws:
NETWORK_FAILURECLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant .checkCanPlayerMatchAsync() .then(canMatch => { if (canMatch) { FBInstant.matchPlayerAsync('level1'); } });
Tournaments
getTournamentAsync()
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. (Not to be confused with FBInstant.tournament.getTournamentsAsync() which returns a list of eligible tournaments that can be surfaced in-game.)
Returns:
Promise<Tournament> — A promise that resolves with the matched instant tournament a user is playing. This rejects if no instant tournament is found.Throws:
PENDING_REQUESTNETWORK_FAILUREINVALID_OPERATIONTOURNAMENT_NOT_FOUND
Example:
FBInstant.getTournamentAsync() .then(function(tournament) { console.log(tournament.getContextID()); console.log(tournament.getEndTime()); });