Instant Games

Instant Games SDK v8.0 (Network Enabled Zero Permissions)

Updated: Jul 17, 2026
Copy for LLM

Changelog

  1. FBInstant.overlayViews New module added for creation and management of overlay view iFrames to be used for Zero Permissions.
  2. Removal of FBInstant.player.getName() and FBInstant.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.
  3. Added FBInstant.openExternalLinkAsync(url) for opening approved external URLs after platform confirmation.
  4. Added FBInstant.player.getAssociatedAppsASIDAsync() for retrieving ASIDs for linked associated apps. See Cross-play Management for more information
  5. Added FBInstant.player.getSignedAssociatedAppsASIDAsync() for retrieving signed ASIDs for linked associated apps.
  6. Added FBInstant.player.createNEZPNotificationContentAsync() for creating NEZP notification content.
  7. Added FBInstant.player.getAgeCategoryAsync() for retrieving the player’s age category.
  8. Added destroyAsync() to FBInstant.overlayViews for 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 surfaceDescription
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:
ParameterTypeDescription
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_PARAM
  • NETWORK_FAILURE
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
  • INVALID_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.
});

shareAsync()

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:
ParameterTypeDescription
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_PARAM
  • NETWORK_FAILURE
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
  • INVALID_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:
ParameterTypeDescription
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_PARAM
  • PENDING_REQUEST
  • INVALID_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:
ParameterTypeDescription
score
number
An integer value representing the player’s score at the end of an activity.
Returns:void
Example:
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:
ParameterTypeDescription
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 successfully
Throws:
  • CLIENT_UNSUPPORTED_OPERATION
  • INVALID_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:
ParameterTypeDescription
payload
A payload that describes the update.
Returns:Promise<void> — A promise that resolves when Facebook gives control back to the game.
Throws:
  • INVALID_PARAM
  • PENDING_REQUEST
  • INVALID_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:
ParameterTypeDescription
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_INPUT
  • INVALID_PARAM
  • PENDING_REQUEST
  • CLIENT_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 otherwise
Throws:
  • PENDING_REQUEST
  • CLIENT_REQUIRES_UPDATE
  • INVALID_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_INPUT
  • PENDING_REQUEST
  • CLIENT_REQUIRES_UPDATE
  • INVALID_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:
ParameterTypeDescription
percentage
number
A number between 0 and 100.
Returns:void
Example:
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 game
Example:
// 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:
ParameterTypeDescription
sessionData
Object
An arbitrary data object, which must be less than or equal to 1000 characters when stringified.
Returns:void
Example:
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_PARAM
  • CLIENT_UNSUPPORTED_OPERATION
Example:
FBInstant.startGameAsync().then(function() {
  myGame.start();
});

quit()

Quits the game.
Returns:void
Example:
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:
ParameterTypeDescription
func
Function
A function to call when a pause event occurs.
Returns:void
Example:
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:
ParameterTypeDescription
func
Function
A function to call when a resume event occurs.
Returns:void
Example:
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:
ParameterTypeDescription
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:void
Example:
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:
PropertyTypeDescription
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
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:
PropertyTypeDescription
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:
PropertyTypeDescription
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:
PropertyTypeDescription
url
string
The URL of the media content.

ErrorCode

Error codes that may be returned by the Instant Games API
Properties:
PropertyTypeDescription
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 ErrorCode

APIErrorArgs

Arguments for creating an API Error.
Properties:
PropertyTypeDescription
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:
PropertyTypeDescription
code
- The relevant error code
message
string
- A message describing the error
extraData
string(optional)
- Optional extra data for logging purposes

Ads

loadBannerAdAsync()

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:
ParameterTypeDescription
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_LIMITED
  • INVALID_PARAM
  • CLIENT_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);
  });

hideBannerAdAsync()

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:
ParameterTypeDescription
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_INSTANCES
  • CLIENT_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:
ParameterTypeDescription
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_INSTANCES
  • CLIENT_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:
PropertyTypeDescription
adInstanceID
string
- Unique identifier for the ad instance
placementID
string
- Audience Network placement ID for the ad

AdInstance

constructor()

Creates a new AdInstance.
Parameters:
ParameterTypeDescription
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 ad

loadAsync()

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 preloaded
Throws:
  • ADS_FREQUENT_LOAD
  • ADS_NO_FILL
  • INVALID_PARAM
  • NETWORK_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 ad
Throws:
  • ADS_NOT_LOADED
  • INVALID_PARAM
  • NETWORK_FAILURE
  • INVALID_OPERATION
  • RATE_LIMITED
  • USER_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:
PropertyTypeDescription
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:
PropertyTypeDescription
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:
PropertyTypeDescription
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 ErrorCode

APIErrorArgs

Arguments for creating an API Error.
Properties:
PropertyTypeDescription
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:
PropertyTypeDescription
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:
ParameterTypeDescription
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_PARAM
  • NETWORK_FAILURE
  • USER_INPUT
  • PENDING_REQUEST
  • CLIENT_UNSUPPORTED_OPERATION
  • INVALID_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_FAILURE
  • CLIENT_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_REQUEST
  • NETWORK_FAILURE
  • INVALID_OPERATION
  • TOURNAMENT_NOT_FOUND
Example:
FBInstant.getTournamentAsync()
  .then(function(tournament) {
     console.log(tournament.getContextID());
     console.log(tournament.getEndTime());
  });