Class FBInstant

The main entry point to the Facebook Instant Games SDK.

Inheritance

object

FBInstant

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Meta.InstantGames

Assembly: Unity.Meta.InstantGames.Sdk.dll

Syntax

public static class FBInstant

Properties

Community

Contains functions and properties related to the gaming community.

Declaration

public static Community Community { get; }

Property Value

Type	Description
Community

Context

Contains functions and properties related to the current game context.

Declaration

public static Context Context { get; }

Property Value

Type	Description
Context

GraphApi

Contains functions and properties related to Graph APIs.

Declaration

public static GraphApi GraphApi { get; }

Property Value

Type	Description
GraphApi

Payments

Contains functions and properties related to payments and purchases of game products.

Declaration

public static Payments Payments { get; }

Property Value

Type	Description
Payments

Player

Contains functions and properties related to the current player.

Declaration

public static Player Player { get; }

Property Value

Type	Description
Player

Room

Contains functions and properties related to the Messenger Rooms environment.

Declaration

public static Room Room { get; }

Property Value

Type	Description
Room

Squads

Contains functions and properties related to gaming squads.

Declaration

public static GamingSquads Squads { get; }

Property Value

Type	Description
GamingSquads

Tournament

Contains functions and properties related to tournaments.

Declaration

public static Tournaments Tournament { get; }

Property Value

Type	Description
Tournaments

Methods

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. Exceptions: PENDING_REQUEST, CLIENT_REQUIRES_UPDATE, INVALID_OPERATION

Declaration

public static WebTask<bool> CanCreateShortcutAsync()

Returns

Type	Description
WebTask<bool>	A WebTask<T> that resolves with true if the game can request the player create a shortcut to the game, and false otherwise

CanSwitchNativeGameAsync()

Checks if the current player can call SwitchNativeGameAsync(string) to switch to a native game.

Declaration

public static WebTask<bool> CanSwitchNativeGameAsync()

Returns

Type	Description
WebTask<bool>	A WebTask<T> that resolves with true if the current player can switch to a native game and false otherwise.

CheckCanPlayerMatchAsync()

Checks if the current player is eligible to call MatchPlayerAsync(string, bool, bool). Exceptions: NETWORK_FAILURE, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask<bool> CheckCanPlayerMatchAsync()

Returns

Type	Description
WebTask<bool>	A WebTask that resolves withtrue if the user can match with other players and false otherwise.

CreateShortcutAsync()

Prompts the user to create a shortcut to the game if they are eligible to. Can only be called once per session. Exceptions: USER_INPUT, PENDING_REQUEST, CLIENT_REQUIRES_UPDATE, INVALID_OPERATION

Declaration

public static WebTask CreateShortcutAsync()

Returns

Type	Description
WebTask	A WebTask.

GetEntryPointAsync()

Returns the entry point that the game was launched from. Call this function only after FBInstant.StartGameAsync() resolves.

Declaration

public static WebTask<string> GetEntryPointAsync()

Returns

Type	Description
WebTask<string>	A WebTask<T> containing the name of the entry point from which the user started the game.

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 function returns null for older mobile clients, as well as when there is no data associated with the particular entry point. Call this function only after InitializeAsync() resolves.

Declaration

public static string GetEntryPointData()

Returns

Type	Description
string	Data associated with the current entry point, serialized as a JSON string.

GetInterstitialAdAsync(string)

Attempt to create an instance of an interstitial ad. This instance can then be preloaded and presented. Exceptions: ADS_TOO_MANY_INSTANCES, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask<AdInstance> GetInterstitialAdAsync(string placementID)

Parameters

Type	Name	Description
string	placementID	The placement ID that's been set up in your Audience Network settings.

Returns

Type	Description
WebTask<AdInstance>	A WebTask<T> that resolves with an AdInstance or rejects with an APIError if it couldn't be created.

GetLeaderboardAsync(string)

Fetch a specific leaderboard belonging to the game. Exceptions: LEADERBOARD_NOT_FOUND, NETWORK_FAILURE, CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION, INVALID_PARAM

Declaration

public static WebTask<Leaderboard> GetLeaderboardAsync(string name)

Parameters

Type	Name	Description
string	name	The name of the leaderboard. Each leaderboard for an Instant Game must have its own unique name.

Returns

Type	Description
WebTask<Leaderboard>	A WebTask<T> that resolves with the matching Leaderboard or rejects with an APIError if one is not found.

GetLocale()

Returns the current locale. Refer to the following file for a complete list of supported locale values: https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml. Use this function to determine what languages the current game should be localized with. The value won't be accurate until FBInstant.InitializeAsync() resolves.

Declaration

public static string GetLocale()

Returns

Type	Description
string	The current locale.

GetPlatform()

Returns the platform on which the game is currently running. The value is null until FBInstant.InitializeAsync() resolves.

Declaration

public static Platform GetPlatform()

Returns

Type	Description
Platform	A Platform that represents the platform on which the game is currently running.

GetRewardedInterstitialAsync(string)

Attempt to create an instance of rewarded interstitial. This instance can then be preloaded and presented. Exceptions: ADS_TOO_MANY_INSTANCES, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask<AdInstance> GetRewardedInterstitialAsync(string placementID)

Parameters

Type	Name	Description
string	placementID	The placement ID that's been set up in your Audience Network settings.

Returns

Type	Description
WebTask<AdInstance>	A WebTask<T> that resolves with an AdInstance or rejects with an APIError if it couldn't be created.

GetRewardedVideoAsync(string)

Attempt to create an instance of rewarded video. This instance can then be preloaded and presented. Exceptions: ADS_TOO_MANY_INSTANCES, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask<AdInstance> GetRewardedVideoAsync(string placementID)

Parameters

Type	Name	Description
string	placementID	The placement ID that's been set up in your Audience Network settings.

Returns

Type	Description
WebTask<AdInstance>	A WebTask<T> that resolves with an AdInstance or rejects with an APIError if it couldn't be created.

GetSDKVersion()

Returns the string representation of this SDK version.

Declaration

public static string GetSDKVersion()

Returns

Type	Description
string	The SDK version.

GetSupportedAPIs()

Provides a list of API functions that are supported by the client. Note that these are the names from the JavaScript SDK. The corresponding C# property and method names begin with a capital letter.

Declaration

public static string[] GetSupportedAPIs()

Returns

Type	Description
string[]	A list of API functions that the client explicitly supports.

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. Exceptions: PENDING_REQUEST, NETWORK_FAILURE, INVALID_OPERATION, TOURNAMENT_NOT_FOUND

Declaration

public static WebTask<Tournament> GetTournamentAsync()

Returns

Type	Description
WebTask<Tournament>	A WebTask<T> containing a Tournament.

HideBannerAdAsync()

Attempt to hide a banner ad. Exceptions: CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask HideBannerAdAsync()

Returns

Type	Description
WebTask	A WebTask that resolves after the ad is hidden.

InitializeAsync()

Initializes the SDK library. This should be called before any other SDK functions.

Declaration

public static WebTask InitializeAsync()

Returns

Type	Description
WebTask	A WebTask that resolves when the SDK is ready to use.

InviteAsync(InvitePayload)

Invokes a dialog to let the user invite one or more people to the game. You can attach a blob of data to the invitation, which every game session launched from the invitation can access from GetEntryPointData(). This data must not exceed 1,000 characters when stringified. The user may choose to cancel the action and close the dialog. The returned promise resolves when the dialog is closed regardless of whether the user invited people or not. Customize the sections included in the dialog by using the sections property. This can specify which sections to include, how many results to include in each section, and in what order the sections should appear. The last section includes as many results as possible. If no sections are specified, the default section settings are applied. The filters property allows for filtering the results. If no results return when the filters are applied, the results are generated without the filters. Exceptions: INVALID_PARAM, NETWORK_FAILURE, PENDING_REQUEST, CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION

Declaration

public static WebTask InviteAsync(InvitePayload payload)

Parameters

Type	Name	Description
InvitePayload	payload	Specify what to share.

Returns

Type	Description
WebTask	A WebTask that resolves when the share is completed or cancelled.

LoadBannerAdAsync(string, string)

Attempt to load or re-load a banner ad. Exceptions: RATE_LIMITED, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask LoadBannerAdAsync(string placementID, string bannerPosition = "bottom")

Parameters

Type	Name	Description
string	placementID	The placement ID that's been set up in your Audience Network settings.
string	bannerPosition	An optional parameter that sets the position of the banner to be "top" or "bottom." The default is a banner at the bottom of the screen.

Returns

Type	Description
WebTask	A WebTask<T> that resolves after loading a banner ad, or rejects with an APIError if it couldn't be created.

LogEvent(string, double?, string)

Logs an app event with FB Analytics. Refer to the Facebook SDK for JavaScript Reference for more details about FB Analytics.

Declaration

public static APIError LogEvent(string eventName, double? valueToSum = null, string parameters = null)

Parameters

Type	Name	Description
string	eventName	Name of the event. Must be 2 to 40 characters and can only contain '_', '-', ' ', and alphanumeric characters.
double?	valueToSum	An optional numeric value that FB Analytics can calculate a sum with.
string	parameters	An optional object, serialized as a JSON string, 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

Type	Description
APIError	Returns an APIError if the event failed to log; otherwise returns null.

MatchPlayerAsync(string, bool, bool)

Attempts to match the current player with other users looking for people to play with.
There are two matching mechanisms:
1. Synchronous (realtime) match: Matches the current player with other users looking for people to play with. If successful, a new Messenger group thread is created containing the matched players and the player switches into that thread's context. This resolves when the player successfully switches into the newly matched context.
2. Asynchronous (offline) match: Player starting an offline match will be added to a group thread right away. Players can leave the game while waiting for more players to join. Once matched with other players, the player is switched into the matched thread's context. This resolves when the player is successfully added to the group thread and switched into the matched context.
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. Change the values in fbapp-config.json. Refer to the Bundle Config documentation for documentation about fbapp-config.json.Exceptions: INVALID_PARAM, NETWORK_FAILURE, USER_INPUT, PENDING_REQUEST, CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION

Declaration

public static WebTask<Leaderboard> MatchPlayerAsync(string matchTag = null, bool switchContextWhenMatched = false, bool offlineMatch = false)

Parameters

Type	Name	Description
string	matchTag	Optional extra information about the player used to group them with similar players. Players are only 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.
bool	switchContextWhenMatched	Optional extra parameter that specifies whether the player is immediately switched to the new context when a match is found. By default, this is false, which means the player needs to press play after being matched to switch to the new context.
bool	offlineMatch	Optional extra parameter that specifies whether to start a match asynchronously. By default this is false, which means the game will start a match synchronously.

Returns

Type	Description
WebTask<Leaderboard>	A WebTask that resolves when the player is added to a group thread and switched into the thread's context.

OnPause(Action)

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

Declaration

public static void OnPause(Action func)

Parameters

Type	Name	Description
Action	func	A function to call when a pause event occurs.

PerformHapticFeedbackAsync()

Requests and performs haptic feedback on supported devices. Exceptions: CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION

Declaration

public static WebTask PerformHapticFeedbackAsync()

Returns

Type	Description
WebTask	A WebTask when haptic feedback was requested successfully.

PostSessionScoreAsync(double)

Posts a player's score to Facebook and resolves when the score has been posted. This API should only be called at the end of an activity (example: when the player has no lives left to continue the game). This API is rate-limited when called too frequently. Score posted using this API should be consistent and comparable across game sessions. For example, if Player A acheives 200 points in a session and Player B achieves 320 points in a session, these two scores should be generated from activities where the scores are fair to be compared and ranked against each other. Exceptions: RATE_LIMITED

Declaration

public static WebTask PostSessionScoreAsync(double score)

Parameters

Type	Name	Description
double	score	An integer value representing the player's score at the end of an activity.

Returns

Type	Description
WebTask	A WebTask that resolves when all platform behavior (such as dialogs) generated from the posted score has completed and the game resumes. If the behavior resulted in a social context change, that will be reflected by the time the WebTask resolves.

Quit()

Quits the game.

Declaration

public static void Quit()

RegisterScreenshotProvider(Action<Func<ScreenshotPayload, WebTask>>)

Registers a callback function that will get called when the user attempts to capture a screenshot of the game. Through the callback, the game can pass an image along with metadata that associates the screenshot. Users will then have the option to share the screenshot, or save it to their library. Exceptions: INVALID_PARAM, CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION

Declaration

public static void RegisterScreenshotProvider(Action<Func<ScreenshotPayload, WebTask>> provider)

Parameters

Type	Name	Description
Action<Func<ScreenshotPayload, WebTask>>	provider	A callback function that will get called when the user requests to capture a screenshot.

SetLoadingProgress(double)

Reports the game's initial loading progress. Call this method between InitializeAsync() and StartGameAsync().

Declaration

public static void SetLoadingProgress(double percentage)

Parameters

Type	Name	Description
double	percentage	A number between 0 and 100 indicating the percentage of the game that has loaded.

SetSessionData(string)

Sets the data associated with the individual gameplay session for the current context. This function should be called whenever the game updates the current session data. This session data may be used to populate a variety of payloads, such as game play webhooks.

Declaration

public static void SetSessionData(string sessionData)

Parameters

Type	Name	Description
string	sessionData	An arbitrary data object, serialized as a JSON string. This string must represent a JSON object such as {"key": "value"} and be no more than 1,000 characters.

ShareAsync(SharePayload)

Invokes a dialog to let the user share specified content, for example, as a post on their timeline. You can attach a data blob to the share dialog, which is accessible in every game session launched from it via from GetEntryPointData(). This data must not exceed 1,000 characters when stringified. The user may choose to cancel the share action and close the dialog. The returned WebTask resolves when the dialog closes regardless if the user shared the content or not. Exceptions: INVALID_PARAM, NETWORK_FAILURE, PENDING_REQUEST, CLIENT_UNSUPPORTED_OPERATION, INVALID_OPERATION

Declaration

public static WebTask ShareAsync(SharePayload payload)

Parameters

Type	Name	Description
SharePayload	payload	The content to be shared.

Returns

Type	Description
WebTask	A WebTask that resolves when the share is completed or canceled.

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 WebTask resolves. Exceptions: INVALID_PARAM, CLIENT_UNSUPPORTED_OPERATION

Declaration

public static WebTask StartGameAsync()

Returns

Type	Description
WebTask	A WebTask that resolves when the game should start.

SwitchGameAsync(string, string)

Requests that the client switch to a different Instant Game. If the switch is successful, the client loads the new game; otherwise, the API rejects the request. Exceptions: USER_INPUT, INVALID_PARAM, PENDING_REQUEST, CLIENT_REQUIRES_UPDATE

Declaration

public static WebTask SwitchGameAsync(string appID, string data = null)

Parameters

Type	Name	Description
string	appID	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, use the Business Manager.
string	data	An optional data payload, serialized as a JSON string. This string must represent a JSON object such as {"key": "value"} and be no more than 1,000 characters. This is set as the entry point data for the game being switched to.

Returns

Type	Description
WebTask	A WebTask that resolves when the game switch is successful.

SwitchNativeGameAsync(string)

Request that the client switch to its native (Android/iOS) game. The API rejects if the switch fails. If it succeeds, the client opens the Game or Store.Exceptions: CLIENT_UNSUPPORTED_OPERATION, PENDING_REQUEST, INVALID_OPERATION.

Declaration

public static WebTask SwitchNativeGameAsync(string data = null)

Parameters

Type	Name	Description
string	data	An optional data payload, serialized as a JSON string. This string must represent a JSON object such as {"key": "value"} and be no more than 1,000 characters. This will be set as the entrypoint data for the game being switched to.

Returns

Type	Description
WebTask	A WebTask that resolves when the user has successfully switched to a native game.

UpdateAsync(CustomUpdatePayload)

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 WebTask will resolve/reject when Facebook returns control to the game. Exceptions: INVALID_PARAM, PENDING_REQUEST, INVALID_OPERATION

Declaration

public static WebTask UpdateAsync(CustomUpdatePayload payload)

Parameters

Type	Name	Description
CustomUpdatePayload	payload	A payload that describes the update

Returns

Type	Description
WebTask	A WebTask that resolves when Facebook gives control back to the game.

UpdateAsync(LeaderboardUpdatePayload)

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 WebTask will resolve/reject when Facebook returns control to the game. Exceptions: INVALID_PARAM, PENDING_REQUEST, INVALID_OPERATION

Declaration

public static WebTask UpdateAsync(LeaderboardUpdatePayload payload)

Parameters

Type	Name	Description
LeaderboardUpdatePayload	payload	A payload that describes the update

Returns

Type	Description
WebTask	A WebTask that resolves when Facebook gives control back to the game.