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.
ConnectedPlayerConnected Player objects have been updated. They no longer have an 'id' property. Instead, they now provide the following properties:
PlatformWe'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.
Custom Update TemplatesCalls 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).
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:
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.
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.
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.
IMMEDIATE CLEARClears 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.
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.
We are now providing a flexible platform that allows the developer
to keep a customizable leaderboard using their own backend.
With the new flexible platform, sharing is not limited to a screenshot
but can be any image. Replaced by
FBInstant.quit() which yields control back to the player.
FBInstant.quit() which handles any exit conditions.
Yields control back to the Facebook Messenger UI. Used when the game
should exit or is an unrecoverable error state.
Sends a fully customizable message into a Messenger conversation.
Allows to get a generic data blob sent with the update message
Allows developer to set a handler for when the game is interrupted
(e.g., app switch, phone call)
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.
Presents the user an interface to change the current game context
(e.g. to change Messenger threads).
Switches to an arbitrary context ID (e.g. to switch to a specific
Messenger thread based on a known context ID).
Displays a share dialog for the user to share game content to their friends.
Allows the developer to set a custom payload for the current session
in a particular context. May be used to populate bot webhooks.
Logs an event to Facebook Analytics
Returns the type of the context from where the game is being played.
(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.
FBInstant.player.getName returns localized display name of the current player.
FBInstant.player.getPhoto returns a URL to the profile photo of the current player.
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.
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.
(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.
(New) Key-value storage
FBInstant.player.setDataAsync allow you to save information from the player on Facebook's backend.
It's now returning the actual locale for the user, instead of the default test value
(Update) FBInstant.player.id: It's now coming from our backend, so should work across all apps and devices for the same user.
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:
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
(New) Platform information:
FBInstant.platform property, that once initialized will be populated with one of 3 values:
(New) Locale information:
FBInstant.locale property, that once initialized will be populated with the user's locale code.
(New) Player Id information:
FBInstant.player.id property, that once initialized will be populated with the player's anonymous id.
Removed unimplemented methods: All methods previously tagged with [Not Implemented] have been removed. They will be re-added once implemented.
Included API Versioning on SDK file name:
This file is now accessible via
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.