Instant Games

Facebook Instant Games extension

Instant Games is a new way for people to play games across Facebook platforms. Powered by HTML5 technology, it allows people to find and play games directly in the News Feed or Messenger conversations, on both desktops and mobile devices. This extension provides an integration with the Facebook Instant Games API. The extension currently supports version 6.3 of the Facebook Instant Games API.

Installation

1. Add project dependencies - REQUIRED

You can use the extension in your own project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field under project add:

https://github.com/defold/extension-fbinstant/archive/master.zip

Or point to the ZIP file of a specific release.

2. Preparing index.html - REQUIRED

Configure your game.project HTML5 section according to the manual.

2.1 Report loading progress - OPTIONAL

Facebook Instant Games can show the progress while the game is loaded. It is quite easy to set this up for a Defold game. All that is required is to override the Progress.updateProgress() function and pass along the value to the Instant Games API (this is done for you in the default index.html provided with this extension):

	// Set up a progress listener and feed progress to FBInstant
	Progress.updateProgress = function (percentage, text) {
		FBInstant.setLoadingProgress(percentage);
	}

2.2 Early API initialization - OPTIONAL

It has been observed that the progress updates do not work properly on Android. The progress stays at 0 and immediately jumps to 100 when the game has finished loaded. This seems to be caused by the Instant Games API not being initialized until after the game has loaded. In order to avoid this it is recommended to initialize the Instant Games API and flag this to the extension (this is done for you in the default index.html provided with this extension):

    // Do early initialization of FBInstant
    // This is required to be able to properly update the loading
    // progress above.
    FBInstant.initializeAsync().then(function() {
        // This will be checked by the FBInstant Defold extension
		Module._fbinstant_inited = true;
	});

3. Create a Facebook App - REQUIRED

You also need to create a Facebook App in the Facebook App Dashboard where Instant Games is enabled. Please refer to the Getting Started documentation on the Instant Games page for further instructions.

4. Create a Bundle Configuration file - OPTIONAL

You can include an fbapp-config.json configuration file in the application bundle that you publish. The file is put in the root directory of your bundle to specify settings for your application. These settings will apply to all users who the bundle is served to. This enables you to launch different bundles along with different application settings to different audiences. Read more about the format here.

Defold can automatically include this file in the HTML5 bundle using the Bundle Resources setting in game.project. Create a folder in your project to hold the configuration file:

/my_bundle_resources/web/fbapp-config.json

And set my_bundle_resources as the value in the Bundle Resources field in game.project.

Usage

FBInstant API

The extension wraps the Instant Games Javascript API in a Lua interface. The Instant Games extension is accessible through the fbinstant.* namespace where it wraps the Javascript SDK in a Lua API. The extension provides an almost 1 to 1 mapping between the Javascript SDK and the Lua API.

For example, consider this Javascript code:

FBInstant.initializeAsync().then(function() {
    FBInstant.startGameAsync().then(function() {
      var playerID = FBInstant.player.getID();
      var playerName = FBInstant.player.getName();
    });
});

The corresponding Lua code looks like this:

fbinstant.initialize(function(self, success)
    fbinstant.start_game(function(self, success)
        local player_id = fbinstant.get_player().id
        local player_name = fbinstant.get_player().name
    end)
end)

From promises to callbacks

The async API functions are Promise based in Javascript while the Lua counterparts are callback based.

Facebook Instant Games and LiveUpdate

The LiveUpdate functionality of Defold can be combined with Facebook Instant Games to create really small application bundles where additional content can be downloaded while the player is progressing through game. Combine the excluded content with the application bundle in a single zip file when uploading to the web hosting provided by Facebook Instant Games. When loading the excluded content you’re required to load the content from the same base URL as the rest of the game is loaded from. There is a helper module that will get the base URL from the browser:

	local baseurl = require "fbinstant.baseurl"

	local missing_resources = collectionproxy.missing_resources("#level3")
	for _,resource in ipairs(missing_resources) do
		local id = http.request(baseurl.get() .. resource, "GET", callback)
	end

Reducing bundle size

The Facebook Instant Games best practices recommends an initial loading time less than 5 seconds. Defold adds little overhead to your games and provide a number of tools allowing you to reduce the size of your game:

Removing unused engine features: A standard Defold engine for HTML5 is a little less than 1.2MB in size when compressed using gzip, but the engine size can be significantly reduce by removing parts of the engine that aren’t used by your game. Which parts of the engine to remove is specified in an “app.manifest”, referenced from the Native Extension section of your “game.project” file.
This functionality is still in an alpha state and needs further documentation. Tools for generating app.manifests file can be found here: https://forum.defold.com/t/stripping-appmanifest-maker/16059
Apply texture compression: Texture compression is an efficient method of reducing both the amount of runtime memory needed by your textures and the size the textures takes in your application bundle. Read more about how to work with texture compression in Texture Profiles manual.
Exclude content from boot and download it during run-time: Many games split the game content into levels or episodes. For those types of games it often make sense to postpone loading of game content until the player has downloaded and started playing the game.

This process of excluding parts of the game content, storing it on a server and then downloading and caching it while the game is running is perfect for reducing the application size of an Instant Game. The entire process is handled by Defold’s Live Update system.

Source code

The source code is available on GitHub

Examples

Balls game

A bare bones “game” with code to initialize and end a Facebook Instant game session can be found in the examples/balls folder

Tic Tac Toe game

A Tic Tac Toe game is available in a separate repository.

API reference

An example project with all APIs implemented can be found in the examples/apis folder

Lifecycle functions

fbinstant.initialize(callback)

Initialize the Facebook Instant Games SDK.

PARAMETERS

callback (function) - Function to call when the SDK is initialized

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.start_game(callback)

Indicate that the game is ready to start.

PARAMETERS

callback (function) - Function to call when the game has started

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.switch_game(app_id, data, callback)

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

app_id (string) - The Application ID of the Instant Game to switch to.
data (string) - Optional JSON encoded object containing entrypoint data for the game being switched to.
callback (function) - Function to call if the switch fails

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.update(data, callback)

Update the game session.

PARAMETERS

data (string) - JSON encoded object containing game information (refer to the CustomUpdatePayload object of the Javascript API)
callback (function) - Function to call when the value has been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.on_pause(callback)

Set a callback to be fired when a pause event is triggered.

PARAMETERS

callback (function) - Function to call when the game has started

The callback function is expected to accept the following values:

self (userdata) - Script self reference

fbinstant.quit()

Quit the current game session.

fbinstant.set_loading_progress()

Report the game’s initial loading progress.

PARAMETERS

progress (number) - A number between 0 and 100

Player functions

fbinstant.get_player()

Get information about the player.

RETURN

player (table) - Player information

The player table contains the following key-value pairs:

name (string) - Player name
id (string) - Player id
photo (string) - URL to the player photo
locale (string) - Player locale

fbinstant.get_signed_player_info(payload, callback)

Fetch the player’s unique identifier along with a signature that verifies that the identifier indeed comes from Facebook without being tampered with.

PARAMETERS

payload (string) - A developer-specified payload to include in the signed response.
callback (function) - Function to call with the list of connected players

The callback function is expected to accept the following values:

self (userdata) - Script self reference
signature (string) - A signature to verify this object indeed comes from Facebook.

fbinstant.get_connected_players(callback)

Get a list of players that are connected to the current player.

PARAMETERS

callback (function) - Function to call with the list of connected players

The callback function is expected to accept the following values:

self (userdata) - Script self reference
players (string) - JSON encoded array of connected player information

Each entry in the players array represents a player with these properties:

id (string) - Id of the connected player
photo (string) - The player’s public profile photo
name (string) - The player’s full name

fbinstant.get_player_data(keys, callback)

Retrieve data from the designated cloud storage of the current player.

PARAMETERS

keys (string) - An array of unique keys to retrieve data for.
callback (function) - Function to call when the data has been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
data (string) - JSON encoded key-value pair map containing the requested data.

fbinstant.set_player_data(data, callback)

Set data to be saved to the designated cloud storage of the current player.

PARAMETERS

data (string) - JSON encoded key-value pairs containing player data
callback (function) - Function to call when the data has been saved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.flush_player_data(callback)

Immediately flushes any changes to the player data to the designated cloud storage.

PARAMETERS

callback (function) - Function to call when the data has been flushed

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.get_player_stats([stats,] callback)

Retrieve stats from the designated cloud storage of the current player.

PARAMETERS

stats (string) - Optional JSON encoded array of unique keys to retrieve stats for. If the function is called without it, it will fetch all stats.
callback (function) - Function to call when the stat has been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
stats (string) - JSON encoded key-value pair map containing the requested stats.

fbinstant.set_player_stats(stats, callback)

Set stats to be saved to the designated cloud storage of the current player.

PARAMETERS

stats (string) - JSON encoded key-value pairs containing player stats
callback (function) - Function to call when the stat have been saved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.increment_player_stats(increments, callback)

Increment stats saved in the designated cloud storage of the current player.

PARAMETERS

increments (string) - JSON encoded key-value pairs indicating how much to increment each stat.
callback (function) - Function to call when the stats have been increased

The callback function is expected to accept the following values:

self (userdata) - Script self reference
stats (string) - JSON encoded key-value pairs with the incremented stats

fbinstant.can_subscribe_bot(callback)

Returns whether or not the player is eligible to subscribe to the associated chat bot.

PARAMETERS

callback (function) - Function to call if player can be subscribed to bot

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.subscribe_bot(callback)

Prompts the player to subscribe to the chat bot. Player will only be able to see this bot subscription dialog once for a specific game.

PARAMETERS

callback (function) - Function to call to decide what to do if the player was subscribed or not

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

Context functions

fbinstant.get_context()

Get the current context.

RETURN

id (string) - The context id, or nil if none exists
type (string) - The context type, or nil if none exists (see fbinstant.CONTEXT_* constants)

fbinstant.choose_context([options,] callback)

Opens a context selection dialog for the player.

PARAMETERS

options (string nil) - OPTIONAL! JSON encoded object containing options (refer to the documentation for chooseAsync)
callback (function) - Function to call when a context has been selected. It is now possible to call get_context() to get the context.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
id (string) - The context id, or nil if none exists
type (string) - The context type, or nil if none exists (see fbinstant.CONTEXT_* constants)

fbinstant.create_context(player_id, callback)

Attempts to create or switch into a context between a specified player and the current player.

PARAMETERS

player_id (string) - ID of the player
callback (function) - Function to call when the context has been created

The callback function is expected to accept the following values:

self (userdata) - Script self reference
id (string) - The context id, or nil if none exists
type (string) - The context type, or nil if none exists (see fbinstant.CONTEXT_* constants)

fbinstant.switch_context(context_id, callback)

Request a switch into a specific context.

PARAMETERS

context_id (string) - ID of the context
callback (function) - Function to call when when the switch has been made

The callback function is expected to accept the following values:

self (userdata) - Script self reference
id (string) - The context id, or nil if none exists
type (string) - The context type, or nil if none exists (see fbinstant.CONTEXT_* constants)

fbinstant.get_entry_point_data()

Get entry point data.

RETURN

data (string) - The entry point data as a JSON string

fbinstant.get_entry_point(callback)

Get the entry point that the game was launched from.

PARAMETERS

callback (function) - Function to call when the entry point has been received.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
entry_point (string) - The entry point

fbinstant.set_session_data(data)

Set data associated with the session.

PARAMETERS

data (string) - JSON encoded object containing session data

fbinstant.get_players(callback)

Get the players in the current context.

PARAMETERS

callback (function) - Function to call when the players have been received.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
players (table) - Table with players in the context

Each entry in the players table has the following values:

id (string) - User id
name (string) - User name
photo (string) - URL to a photo of the user

fbinstant.post_session_score(score)

Posts the player’s best score for the session to Facebook.

PARAMETERS

score (number) - An integer value representing the player’s best score in a session.

fbinstant.get_players()

Get the players in the current context.

Platform functions

fbinstant.get_platform()

Gets the active platform the game is running on.

RETURN

platform (string) - The current platform one of “IOS” or “ANDROID” or “WEB” or “MOBILE_WEB”.

fbinstant.get_locale()

The current locale. See https://origincache.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.startGameAsync() resolves.

RETURN

locale (string) - The locale

fbinstant.get_supported_apis()

Gets a list of supported apis by the current platform.

Check this list before attempting to use features which don’t yet work on all platforms such as ads. Refer to the SDK documentation for a complete list of APIs: https://developers.facebook.com/docs/games/instant-games/sdk

RETURN

apis (string) - JSON encoded string with a key value mapping of supported APIs.

EXAMPLE

local apis_json = fbinstant.get_supported_apis()
local apis = json.decode(apis_json)
if apis["getInterstitialAdAsync"] then
    -- load/show interstitial
end

fbinstant.get_sdk_version()

Gets the current SDK version. Can be used as a sanity check.

RETURN

version (string) - Example “6.1”

fbinstant.can_create_shortcut(callback)

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.

Currently only a feature on Android for adding a shortcut to the home screen.

PARAMETERS

callback (function) - Function to call if shortcut can be created

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.create_shortcut(callback)

Prompts the user to create a shortcut to the game if they are eligible to. For now, only for adding a shortcut to the Android home screen. Can only be called once per session.

PARAMETERS

callback (function) - Function to call to decide what to do if a shortcut was or wasn’t created (such as storing data to ask again sometime in the future)

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

fbinstant.share()

Invoke a share dialog.

PARAMETERS

payload (string) - JSON encoded share payload (refer to the SharePayload object from the Javascript API)
callback (function) - Function to call when the share dialog has been closed.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not

Analytics functions

fbinstant.log_event(event_name, value_to_sum, parameters)

Log an app event with FB Analytics.

PARAMETERS

event_name (string) - Name of the event (refer to the Javascript API for event name limitations)
value_to_sum (number) - An numeric value that FB Analytics can calculate a sum with.
parameters (string) - JSON encoded object of key value pairs (refer to the Javascript API for parameter limitations)

Ads functions

Displaying an ad is a three step process:

Creating an ad instance for a placement (using a placement id)
Preloading the ad instance (using the ad id returned from #1)
Showing the ad instance (using the ad id returned from #1)

fbinstant.get_interstitial_ad(placement, callback)

Get an interstitial ad instance.

PARAMETERS

placement (string) - The placement ID that’s been setup in your Audience Network settings
callback (function) - Function to call when the interstitial ad has been created

The callback function is expected to accept the following values:

self (userdata) - Script self reference
ad_id (string) - Id of the ad instance
error (string) - Error code if something went wrong

fbinstant.load_interstitial_ad(ad_id, callback)

Preload an interstitial ad.

PARAMETERS

ad_id (string) - Id of the ad instance to preload
callback (function) - Function to call when the interstitial ad has loaded

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not
error (string) - Error code if something went wrong

fbinstant.show_interstitial_ad(ad_id, callback)

Present an interstitial ad.

PARAMETERS

ad_id (string) - Id of the ad instance to show
callback (function) - Function to call when user finished watching the ad

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not
error (string) - Error code if something went wrong

fbinstant.get_rewarded_video(placement, callback)

Get a rewarded video instance.

PARAMETERS

placement (string) - The placement ID that’s been setup in your Audience Network settings
callback (function) - Function to call when the rewarded video has loaded

The callback function is expected to accept the following values:

self (userdata) - Script self reference
ad_id (boolean) - Id of the crated ad instance
error (string) - Error code if something went wrong

fbinstant.load_rewarded_video(ad_id, callback)

Preload a rewarded video.

PARAMETERS

ad_id (string) - Id of the ad instance to preload
callback (function) - Function to call when the rewarded video has loaded

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not
error (string) - Error code if something went wrong

fbinstant.show_rewarded_video(ad_id, callback)

Present the rewarded video.

PARAMETERS

placement (string) - Id of the ad instance to show
callback (function) - Function to call when user finished watching the ad

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Indicating if the operation was successful or not
error (string) - Error code if something went wrong

Leaderboard functions

fbinstant.get_leaderboard(name, callback)

Get information about a leaderboard.

PARAMETERS

name (string) - Name of the leaderboard to get
callback (function) - Function to call with leaderboard information

The callback function is expected to accept the following values:

self (userdata) - Script self reference
context_id (string) - The ID of the context that the leaderboard is associated with, or nil if the leaderboard is not tied to a particular context
entry_count (number) - The total number of player entries in the leaderboard

fbinstant.set_leaderboard_score(name, score, extra_data, callback)

Updates the player’s score. If the player has an existing score, the old score will only be replaced if the new score is better than it. NOTE: If the leaderboard is associated with a specific context, the game must be in that context to set a score for the player.

PARAMETERS

name (string) - Name of the leaderboard to set score in
score (number) - The new score for the player. Must be a 64-bit integer number.
extra_data (string nil) - Metadata to associate with the stored score. Must be less than 2KB in size.
callback (function) - Function to call when the score has been set

The callback function is expected to accept the following values:

self (userdata) - Script self reference
score (number) - The current score for the player
extra_data (string) - Metadata to associate with the stored score

fbinstant.get_leaderboard_score(name, callback)

Retrieves the leaderboard’s entry for the current player.

PARAMETERS

name (string) - Name of the leaderboard to get score from
callback (function) - Function to call when the score has been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
rank (number) - The current rank of the player
score (number) - The current score for the player
extra_data (string) - Metadata to associate with the stored score

fbinstant.get_leaderboard_entries(name, count, offset, callback)

Retrieves a set of leaderboard entries, ordered by score ranking in the leaderboard.

PARAMETERS

name (string) - Name of the leaderboard to get entries from
count (number) - The number of entries to attempt to fetch from the leaderboard
offset (number) - The offset from the top of the leaderboard that entries will be fetched from
callback (function) - Function to call when the entries have been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
entries (string) - JSON encoded table of entries

Each entry in entries contains:

rank (number) - The rank of the player’s score in the leaderboard
score (number) - The score associated with the entry
formatted_score (string) - The score associated with the entry, formatted with the score format associated with the leaderboard
timestamp (number) - The timestamp of when the leaderboard entry was last updated
extra_data (string) - The developer-specified payload associated with the score
player_name (string) - The player’s localized display name
player_photo (string) - The url to the player’s public profile photo
player_id (number) - The game’s unique identifier for the player

fbinstant.get_leaderboard_connected_player_entries(name, count, offset, callback)

Retrieves the leaderboard score entries of the current player’s connected players (including the current player), ordered by local rank within the set of connected players.

PARAMETERS

name (string) - Name of the leaderboard to get entries from
count (number) - The number of entries to attempt to fetch from the leaderboard
offset (number) - The offset from the top of the leaderboard that entries will be fetched from
callback (function) - Function to call when the entries have been retrieved

The callback function is expected to accept the following values:

self (userdata) - Script self reference
entries (string) - JSON encoded table of entries

Each entry in entries contains:

rank (number) - The rank of the player’s score in the leaderboard
score (number) - The score associated with the entry
formatted_score (string) - The score associated with the entry, formatted with the score format associated with the leaderboard
timestamp (number) - The timestamp of when the leaderboard entry was last updated
extra_data (string) - The developer-specified payload associated with the score
player_name (string) - The player’s localized display name
player_photo (string) - The url to the player’s public profile photo
player_id (number) - The game’s unique identifier for the player

Payment functions

fbinstant.on_payments_ready(callback)

Sets a callback to be triggered when Payments operations are available.

PARAMETERS

callback (function) - Function to call when Payments operations are available

The callback function is expected to accept the following values:

self (userdata) - Script self reference

fbinstant.get_product_catalog(callback)

Fetches the game’s product catalog.

PARAMETERS

callback (function) - Function to call with the set of products that are registered to the game

The callback function is expected to accept the following values:

self (userdata) - Script self reference
products (table) - The products

Each entry in products contains:

title (string) - The title of the product
product_id (string) - The product’s game-specified identifier
description (string) - The product description
image_uri (string) - A link to the product’s associated image
price (string) - The price of the product
price_currency_code (string) - The currency code for the product

fbinstant.get_purchases(callback)

Fetches all of the player’s unconsumed purchases. As a best practice, the game should fetch the current player’s purchases as soon as the client indicates that it is ready to perform payments-related operations. The game can then process and consume any purchases that are waiting to be consumed.

PARAMETERS

callback (function) - Function to call with the set of purchases that the player has made for the game

The callback function is expected to accept the following values:

self (userdata) - Script self reference
purchases (table) - The set of purchases that the player has made for the game

Each entry in purchases contains:

developer_payload (string) - A developer-specified string, provided during the purchase of the product
payment_id (string) - The identifier for the purchase transaction
product_id (string) - The identifier of the purchased product
purchase_time (string) - Unix timestamp of when the purchase occurred
purchase_token (string) - A token representing the purchase that may be used to consume the purchase
signed_request (string) - Server-signed encoding of the purchase request

fbinstant.purchase(product_id, developer_payload, callback)

Begins the purchase flow for a specific product. Will fail if called before FBInstant.startGameAsync() has finished.

PARAMETERS

product_id (string) - The identifier of the product to purchase
developer_payload (string) - n optional developer-specified payload, to be included in the returned purchase’s signed request
callback (function) - Function to call when the product is successfully purchased by the player.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
purchase (table) - Information about the purchase, same data as an entry returned from fbinstant.get_purchases()

fbinstant.consume_purchase(purchase_token, callback)

Consumes a specific purchase belonging to the current player. Before provisioning a product’s effects to the player, the game should request the consumption of the purchased product. Once the purchase is successfully consumed, the game should immediately provide the player with the effects of their purchase.

PARAMETERS

purchase_token (string) - The purchase token of the purchase that should be consumed
callback (function) - Function to call when the purchase has been consumed successfully.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
success (boolean) - Boolean indicating if the purchase was successfully consumed or not

Matchmaking

fbinstant.check_can_player_match_async(callback)

Checks if the current player is eligible for the matchPlayerAsync API.

PARAMETERS

callback (function) - Function to call when the check has completed

The callback function is expected to accept the following values:

self (userdata) - Script self reference
can_match (boolean) - true if the player is eligible to match with other players and false otherwise
error (string) - Error code if something went wrong

fbinstant.match_player(match_tag, switch_context_when_matched, offline_match, callback)

Attempts to match the current player with other users looking for people to play with.

PARAMETERS

match_tag (string) - Optional extra information about the player used to group them with similar players
switch_context_when_matched (boolean) - Optional extra parameter that specifies whether the player should be immediately switched to the new context when a match is found
offline_match (boolean) - Optional extra parameter that specifies whether to start a match asynchronously.
callback (function) - Function to call when the player has been added to a group thread and switched into the thread’s context.

The callback function is expected to accept the following values:

self (userdata) - Script self reference
error (string) - Error code if something went wrong

Constants

Context

fbinstant.CONTEXT_SOLO

fbinstant.get_context().type

fbinstant.CONTEXT_POST

fbinstant.get_context().type

fbinstant.CONTEXT_THREAD

fbinstant.get_context().type

fbinstant.CONTEXT_GROUP

fbinstant.get_context().type

fbinstant.SHARE_INTENT_INVITE

For fbinstant.share() payload table

fbinstant.SHARE_INTENT_REQUEST

For fbinstant.share() payload table

fbinstant.SHARE_INTENT_CHALLENGE

For fbinstant.share() payload table

fbinstant.SHARE_INTENT_SHARE

For fbinstant.share() payload table

Filter

fbinstant.FILTER_NEW_CONTEXT_ONLY

For fbinstant.choose_context() options table

fbinstant.FILTER_INCLUDE_EXISTING_CHALLENGES

For fbinstant.choose_context() options table

fbinstant.FILTER_NEW_PLAYERS_ONLY

For fbinstant.choose_context() options table

Activity Store

fbinstant.STORE_ACTIVE

For fbinstant.get_stores() activity store status

fbinstant.STORE_ENDED

For fbinstant.get_stores() activity store status

Error Codes

fbinstant.ERROR_ADS_FREQUENT_LOAD

fbinstant.ERROR_ADS_NO_FILL

fbinstant.ERROR_ADS_NOT_LOADED

fbinstant.ERROR_ADS_TOO_MANY_INSTANCES

fbinstant.ERROR_RATE_LIMITED

fbinstant.ERROR_INVALID_PARAM

fbinstant.ERROR_ANALYTICS_POST_EXCEPTION

fbinstant.ERROR_CLIENT_REQUIRES_UPDATE

fbinstant.ERROR_CLIENT_UNSUPPORTED_OPERATION

fbinstant.ERROR_INVALID_OPERATION

fbinstant.ERROR_LEADERBOARD_NOT_FOUND

fbinstant.ERROR_LEADERBOARD_WRONG_CONTEXT

fbinstant.ERROR_NETWORK_FAILURE

fbinstant.ERROR_PAYMENTS_NOT_INITIALIZED

fbinstant.ERROR_PENDING_REQUEST

fbinstant.ERROR_SAME_CONTEXT

fbinstant.ERROR_UNKNOWN

fbinstant.ERROR_USER_INPUT

On this page

Languages

Did you spot an error or do you have a suggestion? Please let us know on GitHub!

GITHUB

Facebook Instant Games extension

Installation

1. Add project dependencies - REQUIRED

2. Preparing index.html - REQUIRED

2.1 Report loading progress - OPTIONAL

2.2 Early API initialization - OPTIONAL

3. Create a Facebook App - REQUIRED

4. Create a Bundle Configuration file - OPTIONAL

Usage

FBInstant API

From promises to callbacks

Facebook Instant Games and LiveUpdate

Reducing bundle size

Source code

Examples

Balls game

Tic Tac Toe game

API reference

Lifecycle functions

fbinstant.initialize(callback)

fbinstant.start_game(callback)

fbinstant.switch_game(app_id, data, callback)

fbinstant.update(data, callback)

fbinstant.on_pause(callback)

fbinstant.quit()

fbinstant.set_loading_progress()

Player functions

fbinstant.get_player()

fbinstant.get_signed_player_info(payload, callback)

fbinstant.get_connected_players(callback)

fbinstant.get_player_data(keys, callback)

fbinstant.set_player_data(data, callback)

fbinstant.flush_player_data(callback)

fbinstant.get_player_stats([stats,] callback)

fbinstant.set_player_stats(stats, callback)

fbinstant.increment_player_stats(increments, callback)

fbinstant.can_subscribe_bot(callback)

fbinstant.subscribe_bot(callback)

Context functions

fbinstant.get_context()

fbinstant.choose_context([options,] callback)

fbinstant.create_context(player_id, callback)

fbinstant.switch_context(context_id, callback)

fbinstant.get_entry_point_data()

fbinstant.get_entry_point(callback)

fbinstant.set_session_data(data)

fbinstant.get_players(callback)

fbinstant.post_session_score(score)

fbinstant.get_players()

Platform functions

fbinstant.get_platform()

fbinstant.get_locale()

fbinstant.get_supported_apis()

fbinstant.get_sdk_version()

fbinstant.can_create_shortcut(callback)

fbinstant.create_shortcut(callback)

Share functions

fbinstant.share()

Analytics functions

fbinstant.log_event(event_name, value_to_sum, parameters)

Ads functions

fbinstant.get_interstitial_ad(placement, callback)

fbinstant.load_interstitial_ad(ad_id, callback)

fbinstant.show_interstitial_ad(ad_id, callback)

fbinstant.get_rewarded_video(placement, callback)

fbinstant.load_rewarded_video(ad_id, callback)

fbinstant.show_rewarded_video(ad_id, callback)

Leaderboard functions

fbinstant.get_leaderboard(name, callback)

fbinstant.set_leaderboard_score(name, score, extra_data, callback)

fbinstant.get_leaderboard_score(name, callback)

fbinstant.get_leaderboard_entries(name, count, offset, callback)

fbinstant.get_leaderboard_connected_player_entries(name, count, offset, callback)

Payment functions

fbinstant.on_payments_ready(callback)

fbinstant.get_product_catalog(callback)

fbinstant.get_purchases(callback)

fbinstant.purchase(product_id, developer_payload, callback)

fbinstant.consume_purchase(purchase_token, callback)

Matchmaking