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 ReferenceLeaderboard.getConnectedPlayerEntriesAsync()
API,
which fetches the score entries of the current player's connected
players from the leaderboard.ConnectedPlayer
Connected Player objects have been updated. They no longer have an
'id' property. Instead, they now provide the following properties:
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.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).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 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.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.(Removed) FBInstant.game.setScore()
We are now providing a flexible platform that allows the developer
to keep a customizable leaderboard using their own backend.
(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()
.
(Removed) FBInstant.endGameAsync()
Replaced by FBInstant.quit()
which yields control back to the player.
(Removed) FBInstant.abort()
Replaced by FBInstant.quit()
which handles any exit conditions.
(New) FBInstant.quit()
Yields control back to the Facebook Messenger UI. Used when the game
should exit or is an unrecoverable error state.
(New) FBInstant.updateAsync()
Sends a fully customizable message into a Messenger conversation.
(New) FBInstant.getEntryPointData()
Allows to get a generic data blob sent with the update message
(New) FBInstant.onPause()
Allows developer to set a handler for when the game is interrupted
(e.g., app switch, phone call)
(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.
(New) FBInstant.context.chooseAsync()
Presents the user an interface to change the current game context
(e.g. to change Messenger threads).
(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).
(New) FBInstant.shareAsync()
Displays a share dialog for the user to share game content to their friends.
(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.
(New) FBInstant.logEvent()
Logs an event to Facebook Analytics
(New) FBInstant.context.getType()
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.
(New) FBInstant.player.getName():
FBInstant.player.getName
returns localized display name of the current player.
(New) FBInstant.player.getPhoto():
FBInstant.player.getPhoto
returns a URL to the profile photo of the current player.
(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.
(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.
(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.getDataAsync
and FBInstant.player.setDataAsync
allow you to save information from the player on Facebook's backend.
(Update) FBInstant.locale:
It's now returning the actual locale for the user, instead of the default test value 'en_US'
(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:
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()
(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
(New) Platform information:
Added the FBInstant.platform
property, that once initialized will be populated with one of 3 values: 'iOS'
, 'android'
or 'web'
(New) Locale information:
Added the FBInstant.locale
property, that once initialized will be populated with the user's locale code.
(New) Player Id information:
Added the 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 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.