Instant Games SDK

In this section you'll find the API Reference for the Instant Games JavaScript SDK. If you're starting a new game, we recommend always using our latest version of the SDK. Click the button below to see the SDK reference for our most up-to-date version:

Instant Games SDK ReferenceBundle Configuration Reference

If you're working on upgrading a previous version of the game, check out the sections below for our changelog and the reference documentation for legacy versions of the SDK.

Note that we strongly recommend developers use the new features available in the 6.0 SDK going forward.

On February 15th we announced the deprecation of legacy score-based Instant Games. From May 15th, games built on versions of the SDK below v5 will cease to work on the platform.

  1. Changelog
  2. Instant Games SDK v6.2 (latest)
  3. Instant Games SDK v6.1
  4. Instant Games SDK v6.0
  5. Instant Games SDK v5.1
  6. Instant Games SDK v5.0

Older versions that will be deprecated after May 15th:

  1. Instant Games SDK v4.1
  2. Instant Games SDK v4.0
  3. Instant Games SDK v3.2
  4. Instant Games SDK v3.1
  5. Instant Games SDK v3.0
  6. Instant Games SDK v2.1 (deprecated)
  7. Instant Games SDK v2.0 (deprecated)
  8. Instant Games SDK v1.1 (deprecated)
  9. Instant Games SDK v1.0 (deprecated)

Changelog

Version 6.2 (see reference)

  1. (New) Connected Player Score Entries Introduces the new Leaderboard.getConnectedPlayerEntriesAsync() API, which fetches the score entries of the current player's connected players from the leaderboard.

Version 6.1 (see reference)

  1. Bot Subscription API The Bot Subscription API allows games to subscribe the player to the game's Messenger bot, if they are not subscribed.
  2. [Android Only] Home Screen Shortcut API The Home Screen Shortcut API allows developers to surface a dialog in-game for players to save the game to their home screen.
  3. Matchmaking API (Update) This release also includes an update for the Matchmaking API. We've added an additional parameter to specify whether you want the game to switch into the newly created context right after the player is matched, or wait until the player has clicked 'Play' in the toast.

Version 6.0 (see reference)

  1. Leaderboards This release includes the new Leaderboards API! A robust suite of APIs are provided, allowing games to fetch their leaderboards, query score entries, set new scores (with support for arbitrary metadata attached to the score), and push structured leaderboard updates to Messenger threads.
  2. Game Switch We're also including a new API for in-game cross-promotion. This is currently in private beta, so please reach out to your partner manager if you're interested in helping test integration of Game Switch API within your games! Game switch is available in Facebook v159+ and Facebook Messenger v153+, for both iOS and Android.

Version 5.1 (see reference)

  1. In-App Purchase APIs Includes in-app purchase APIs for Instant Games. These allow the game to fetch its catalog and player purchases, as well as perform and consume purchases. Currently in private beta.
  2. Matchmaking APIs APIs that allow the game to match the current player into a context with other interested players. Currently in private beta.

Version 5.0 (see reference)

  1. Ad APIs Two new APIs for running Interstitial and Rewarded Video Ads. Requires game to be configured for Ads on Instant Games.
  2. Player Stats API to set, get, and atomically increment integer stats associated with the player. This is complemented by new additions to the Bundle Config, which allow configuring metadata for player stats in order to surface stats through Facebook platform-level integrations.
  3. getEntryPointAsync API to get the entry point from which the game was launched.
  4. Custom Update Dev Localization Addition to the Custom Update API, allowing developers to provide localizations of the update content.
  5. Breaking Change Rename CLIENT_REQUIRES_UPDATE to CLIENT_UNSUPPORTED_OPERATION

Version 4.1 (see reference)

  1. FBInstant.player.getSignedPlayerInfoAsync() Provides a payload of information about the current player, signed with the game's app secret to verify that all the information comes from Facebook and is accurate.
  2. FBInstant.context.getPlayersAsync() Provides a list of all the participants in the context who are active players of the current game. Currently, the usual player information is supported: player ID, name, and photo url.
  3. FBInstant.context.isSizeBetween() Allows the game to check if the number of participants in the context (including non-players) is within a certain range. Only one check per session in a context is allowed; subsequent requests will simply return the original result.
  4. Context Filters We've added support for optional filter arguments to FBInstant.context.chooseAsync(). This will allow games to request filters on the context suggestions, including setting bounds on the context size, restricting results to only new (unplayed) contexts, and including an extra section for existing challenges. This feature is currently rolling out on our clients on the following schedule:
    • iOS - Messenger v133 (August 30)
    • Android - Messenger v135 (September 11)
    • Web - Early September

Version 4.0 (see reference)

  1. (Updated) ConnectedPlayer Connected Player objects have been updated. They no longer have an 'id' property. Instead, they now provide the following properties:
    • .id - The player's ID
    • .name - The player's full name
    • .photo - The player's public profile photo URL
  2. (Updated) Platform We're introducing a new platform type - "MOBILE_WEB". While a mobile web player is not publicly available yet, it will use this platform type when released. Games should ensure that controls are properly set for this platform type in order to provide the best experience for all players.
  3. (New) Custom Update Templates Calls to FBInstant.updateAsync() to send a custom update must now populate a "template" field with the id of the custom update type that is being sent, as defined in the game's Bundle Config file (https://developers.facebook.com/docs/games/instant-games/bundle-config).
  4. (Updated) Context Choose Options - IN PROGRESS We're adding support for optional filters on FBInstant.chooseAsync() that will affect the set of contexts that we suggest to the player. The client implementations are still in progress, but developers may integrate these options into their games now. The initial set of supported options are:
    • minSize - The least amount of players the game would like in a suggested context
    • maxSize - The most amount of players the game would like in a suggested context
    • filters - An array of filters. The first filter supported filter is NEW_CONTEXT_ONLY, which attempts to restrict suggested contexts to those that haven't been played in before.

Version 3.2 (see reference)

  1. FBInstant.getSupportedAPIs() Provides a list of the SDK APIs that are supported by the client. Useful for only surfacing functionality that is available to the game.
  2. FBInstant.player.flushDataAsync() Immediately flushes any queued changes to the player data. Player data is normally persisted in the background, so this provides a way to explicitly know whether a change has been persisted or not.
  3. FBInstant.context.createAsync(playerID) Allows the game to specify a player that the active player should enter into a context with. The specified player must be a connected player of the active player.
  4. Custom Update strategy: IMMEDIATE CLEAR Clears any pending update (such as those set by the "LAST" strategy). This is mainly useful when the game needs to send an important update, but has a pending update that is less valuable and should be cleared in order to prioritize the new update.

Version 3.1 (see reference)

  1. (Updated) FBInstant.updateAsync() Now we accept a parameter "notification" on CustomUpdatePayload to allow developers to explicitly set whether or not the update should trigger a push notification. See documentation for updateAsync for details.

Version 3.0 (see reference)

  1. (Removed) FBInstant.game.setScore() We are now providing a flexible platform that allows the developer to keep a customizable leaderboard using their own backend.

  2. (Removed) FBInstant.takeScreenshotAsync() and FBInstant.sendScreenshotAsync() With the new flexible platform, sharing is not limited to a screenshot but can be any image. Replaced by FBInstant.shareAsync().

  3. (Removed) FBInstant.endGameAsync() Replaced by FBInstant.quit() which yields control back to the player.

  4. (Removed) FBInstant.abort() Replaced by FBInstant.quit() which handles any exit conditions.

  5. (New) FBInstant.quit() Yields control back to the Facebook Messenger UI. Used when the game should exit or is an unrecoverable error state.

  6. (New) FBInstant.updateAsync() Sends a fully customizable message into a Messenger conversation.

  7. (New) FBInstant.getEntryPointData() Allows to get a generic data blob sent with the update message

  8. (New) FBInstant.onPause() Allows developer to set a handler for when the game is interrupted (e.g., app switch, phone call)

  9. (New) FBInstant.player.getConnectedPlayersAsync() Retrieves the IDs of players who are connected to the current player, either as a Facebook friend or as a Messenger contact. Only players who also play the Instant Game are returned.

  10. (New) FBInstant.context.chooseAsync() Presents the user an interface to change the current game context (e.g. to change Messenger threads).

  11. (New) FBInstant.context.switchAsync() Switches to an arbitrary context ID (e.g. to switch to a specific Messenger thread based on a known context ID).

  12. (New) FBInstant.shareAsync() Displays a share dialog for the user to share game content to their friends.

  13. (New) FBInstant.setSessionData() Allows the developer to set a custom payload for the current session in a particular context. May be used to populate bot webhooks.

Version 2.1 (see reference)

  1. (New) FBInstant.logEvent() Logs an event to Facebook Analytics

  2. (New) FBInstant.context.getType() Returns the type of the context from where the game is being played.

Version 2.0 (see reference)

  1. (Breaking change) public API properties updated to functions We have updated all our public API properties like FBInstant.locale to functions like FBInstant.getLocale(). This future-proofs the SDK interfaces for backward compatibility. These functions are all synchronous and return immediately.

  2. (New) FBInstant.player.getName(): FBInstant.player.getName returns localized display name of the current player.

  3. (New) FBInstant.player.getPhoto(): FBInstant.player.getPhoto returns a URL to the profile photo of the current player.

  4. (Update) FBInstant.takeScreenshotAsync(): It used to be FBInstant.takeScreenshot and is renamed to FBInstant.takeScreenshotAsync which returns a promise. The promise will reject if we failed to take a screenshot.

  5. (Update) FBInstant.sendScreenshotAsync(): It used to be FBInstant.sendScreenshot and is renamed to FBInstant.sendScreenshotAsync which returns a promise. The promise will reject if the image is not valid.

Version 1.1 (see reference)

  1. (New) Context Identifier FBInstant.context.id Provides context about where the player started the match from. It's a unique identifier for Messenger Threads or Newsfeed Stories depending on where the game was started from.

  2. (New) Key-value storage FBInstant.player.getDataAsync and FBInstant.player.setDataAsync allow you to save information from the player on Facebook's backend.

  3. (Update) FBInstant.locale: It's now returning the actual locale for the user, instead of the default test value 'en_US'

  4. (Update) FBInstant.player.id: It's now coming from our backend, so should work across all apps and devices for the same user.

Version 1.0 (see reference)

  1. Methods renaming: Previously we had namespaces for specific calls, now we are including the domain for these calls in the method names themselves. Some methods were also renamed to improve expressiveness. This effort resulted in the following renames:

    • FBInstant.loading.setProgress() is now FBInstant.setLoadingProgress()
    • FBInstant.loading.complete() is now FBInstant.startGameAsync()
    • FBInstant.game.setScore() is now FBInstant.setScore()
    • FBInstant.game.asyncYieldControl() is now FBInstant.endGameAsync()
    • FBInstant.media.takeScreenshot() is now FBInstant.takeScreenshot()
    • FBInstant.media.sendPicture() is now FBInstant.sendScreenshot()
    • FBInstant.system.abort() is now FBInstant.abort()

  2. (New) Initialization: Added the method FBInstant.initializeAsync() that should return a promise that, when fulfilled, will set the correct information on the global object. In addition to that, the promise returned by FBInstant.startGameAsync() will only be resolved when the player actually starts to play. So by using this API, it's not necessary to have a "Tap to start" behavior on the game itself

  3. (New) Platform information: Added the FBInstant.platform property, that once initialized will be populated with one of 3 values: 'iOS', 'android' or 'web'

  4. (New) Locale information: Added the FBInstant.locale property, that once initialized will be populated with the user's locale code.

  5. (New) Player Id information: Added the FBInstant.player.id property, that once initialized will be populated with the player's anonymous id.

  6. Removed unimplemented methods: All methods previously tagged with [Not Implemented] have been removed. They will be re-added once implemented.

  7. Included API Versioning on SDK file name: This file is now accessible via fbinstant.1.0.js. Newer releases will always have the version appended to the filename. fbinstant.js will keep at its current version and not evolve. The latest version will always be available at fbinstant.latest.js, although it's not recommended to point to that path directly, as breaking changes might land there.