# "Instant Games SDK v6.3"


## Changelog
0. **FBInstant.postSessionScore**
    This API allows the game to provide Facebook with the player's scores from the current game session. Facebook will use these score signals in various platform integrations to help players discover, compete & reengage with the game.
1. **Offline matchmaking**
    Previously, matchmaking has been synchronous, blocking the game for the player while they wait. This release adds an asynchronous option to "matchPlayerAsync". Players starting an offline match will be added to a group thread right away, and players can leave the game while waiting more players to join. Once matched with others, if still in the game, the player will be added and switched into that matched thread's context.
2. **Data APIs for Player, Context, Locale, & Entry Point to start being accessible after "initializeAsync"**
    We're reviving pre-game start access to data APIs! For example, you can now access the player's locale, or entry point data, while the game is loading. This should help you reduce secondary loading screens and overall loading requirements for your games. This change is available now on Web, and will be available on mobile starting in the following releases: FB for Android v219, Messenger for Android v213, FB for iOS v222, Messenger for iOS v216. Earlier mobile releases will exhibit the prior behavior, so make sure to check for any updated values after "startGameAsync" resolves.

## FBInstant (Core)

Represents the type of the update action to perform.

### getLocale()

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

**Returns:** `string` — The current locale.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var locale = FBInstant.getLocale(); // 'en_US'
```

---

### getPlatform()

The platform on which the game is currently running. The value will always
be null until FBInstant.initializeAsync() resolves.

**Returns:** `?`[`Platform`](#platform) — The platform on which the game is running.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var platform = FBInstant.getPlatform(); // 'IOS'
```

---

### getSDKVersion()

The string representation of this SDK version.

**Returns:** `string` — The SDK version.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var sdkVersion = FBInstant.getSDKVersion(); // '2.0'
```

---

### initializeAsync()

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

**Returns:** `Promise` — A promise that resolves when the SDK is ready to use.

**Throws:**

- `INVALID_OPERATION`

**Example:**

```javascript
FBInstant.initializeAsync().then(function() {
  // Many properties will be null until the initialization completes.
  // This is a good place to fetch them:
  var locale = FBInstant.getLocale(); // 'en_US'
  var platform = FBInstant.getPlatform(); // 'IOS'
  var sdkVersion = FBInstant.getSDKVersion(); // '3.0'
  var playerID = FBInstant.player.getID();
});
```

---

### setLoadingProgress()

Report the game's initial loading progress.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `percentage` | `number` | A number between 0 and 100. |

**Example:**

```javascript
FBInstant.setLoadingProgress(50); // Assets are 50% loaded
```

---

### getSupportedAPIs()

Provides a list of API functions that are supported by the client.

**Returns:** `Array<string>` — List of API functions that the client explicitly supports.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
FBInstant.getSupportedAPIs();
// ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...]
```

---

### 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 will return null for
older mobile clients, as well as when there is no data associated with
the particular entry point.

This function should be called after FBInstant.initializeAsync()
resolves.

**Returns:** `?Object` — Data associated with the current entry point.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
const entryPointData = FBInstant.getEntryPointData();
```

---

### getEntryPointAsync()

Returns the entry point that the game was launched from.

This function should not be called until FBInstant.startGameAsync has
resolved.

**Returns:** `string` — The name of the entry point from which the user started the game

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint));
// 'admin_message'
```

---

### setSessionData()

Sets the data associated with the individual gameplay session for the
current context.

This function should be called whenever the game would like to update the
current session data. This session data may be used to populate a variety
of payloads, such as game play webhooks.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sessionData` | `Object` | An arbitrary data object, which must be less than or equal to 1000 characters when stringified. |

**Example:**

```javascript
FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]});
```

---

### 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 promise
resolves.

**Returns:** `Promise` — A promise that resolves when the game should start.

**Throws:**

- `INVALID_PARAM`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.startGameAsync().then(function() {
  myGame.start();
});
```

---

### shareAsync()

This invokes a dialog to let the user share specified content, as a post
on the user's timeline, for example. A blob of data can be attached to the
share which every game session launched from the share will be able to
access from FBInstant.getEntryPointData(). This data must be less than or
equal to 1000 characters when stringified. The user may choose to cancel
the share action and close the dialog, and the returned promise will
resolve when the dialog is closed regardless if the user actually shared
the content or not.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `payload` | [`SharePayload`](#sharepayload) | Specify what to share. See example for   details. |

**Returns:** `Promise` — A promise that resolves when the share is completed or   cancelled.

**Throws:**

- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `PENDING_REQUEST`
- `CLIENT_UNSUPPORTED_OPERATION`
- `INVALID_OPERATION`

**Example:**

```javascript
FBInstant.shareAsync({
  intent: 'REQUEST',
  image: base64Picture,
  text: 'X is asking for your help!',
  data: { myReplayData: '...' },
}).then(function() {
  // continue with the game.
});
```

---

### updateAsync()

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 promise will resolve/reject when
Facebook returns control to the game.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `payload` | [`UpdatePayload`](#updatepayload) | A payload that describes the update. |

**Returns:** `Promise` — A promise that resolves when Facebook gives control   back to the game.

**Throws:**

- `INVALID_PARAM`
- `PENDING_REQUEST`
- `INVALID_OPERATION`

**Example:**

```javascript
// This will post a custom update. When people launch the game from this
// message, those game sessions will be able to access the specified blob
// of data through FBInstant.getEntryPointData().
FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Join The Fight',
  image: base64Picture,
  text: {
    default: 'X just invaded Y\'s village!',
    localizations: {
      ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' +
      '\u0642\u0631\u064A\u0629 Y!',
      en_US: 'X just invaded Y\'s village!',
      es_LA: '\u00A1X acaba de invadir el pueblo de Y!',
    }
  }
  template: 'VILLAGE_INVASION',
  data: { myReplayData: '...' },
  strategy: 'IMMEDIATE',
  notification: 'NO_PUSH',
}).then(function() {
  // closes the game after the update is posted.
  FBInstant.quit();
});
```

---

### switchGameAsync()

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:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `appID` | `string` | 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, you can use Business Manager:   https://developers.facebook.com/docs/apps/business-manager#update-business. |
| `data` | `Object` _(optional)_ | An optional data payload. This will be set as the   entrypoint data for the game being switched to. Must be less than or   equal to 1000 characters when stringified. |

**Throws:**

- `USER_INPUT`
- `INVALID_PARAM`
- `PENDING_REQUEST`
- `CLIENT_REQUIRES_UPDATE`

**Example:**

```javascript
FBInstant.switchGameAsync('12345678').catch(function (e) {
  // Handle game change failure
});
```

```javascript
FBInstant.switchGameAsync(
  '12345678',
  {referrer: 'game_switch', reward_coins: 30},
).catch(function (e) {
  // Handle game change failure
});
```

---

### 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.

**Returns:** `Promise<boolean>` — Promise that resolves with true if the game can request the player create a shortcut to the game, and false otherwise

**Throws:**

- `PENDING_REQUEST`
- `CLIENT_REQUIRES_UPDATE`
- `INVALID_OPERATION`

**Example:**

```javascript
FBInstant.canCreateShortcutAsync()
  .then(function(canCreateShortcut) {
    if (canCreateShortcut) {
      FBInstant.createShortcutAsync()
        .then(function() {
          // Shortcut created
        })
        .catch(function() {
          // Shortcut not created
        });
    }
  });
```

---

### createShortcutAsync()

Prompts the user to create a shortcut to the game if they are eligible to
Can only be called once per session.
(see [`canCreateShortcutAsync`](#cancreateshortcutasync))

**Throws:**

- `USER_INPUT`
- `PENDING_REQUEST`
- `CLIENT_REQUIRES_UPDATE`
- `INVALID_OPERATION`

**Example:**

```javascript
FBInstant.canCreateShortcutAsync()
  .then(function(canCreateShortcut) {
    if (canCreateShortcut) {
      FBInstant.createShortcutAsync()
        .then(function() {
          // Shortcut created
        })
        .catch(function() {
          // Shortcut not created
        });
    }
  });
```

---

### quit()

Quits the game.

**Example:**

```javascript
FBInstant.quit();
```

---

### onPause()

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | `Function` | A function to call when a pause event occurs. |

**Example:**

```javascript
FBInstant.onPause(function() {
  console.log('Pause event was triggered!');
  pauseGameplay();
})
```

---

### getInterstitialAdAsync()

Attempt to create an instance of interstitial ad. This instance can then be
preloaded and presented.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `placementID` | `string` | The placement ID that's been setup in your   Audience Network settings. |

**Returns:** `Promise` — A promise that resolves with a   [`AdInstance`](#adinstance), or rejects with a [`APIError`](#apierror) if   it couldn't be created.

**Throws:**

- `ADS_TOO_MANY_INSTANCES`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.getInterstitialAdAsync(
  'my_placement_id'
).then(function(interstitial) {
  interstitial.getPlacementID(); // 'my_placement_id'
});
```

---

### isAdBreakTest()

Check if the user is in the ad break testing group

**Returns:** `boolean` — true if the user is in the ad break testing group

---

### getRewardedVideoAsync()

Attempt to create an instance of rewarded video. This instance can then be
preloaded and presented.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `placementID` | `string` | The placement ID that's been setup in your   Audience Network settings. |

**Returns:** `Promise` — A promise that resolves with a   [`AdInstance`](#adinstance), or rejects with a [`APIError`](#apierror) if   it couldn't be created.

**Throws:**

- `ADS_TOO_MANY_INSTANCES`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.getRewardedVideoAsync(
  'my_placement_id'
).then(function(rewardedVideo) {
  rewardedVideo.getPlacementID(); // 'my_placement_id'
});
```

---

### checkCanPlayerMatchAsync()

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

**Returns:** `Promise<boolean>` — A promise that resolves with true if the player   is eligible to match with other players and false otherwise.

**Throws:**

- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant
  .checkCanPlayerMatchAsync()
  .then(canMatch => {
    if (canMatch) {
      FBInstant.matchPlayerAsync('level1');
    }
  });
```

---

### getLeaderboardAsync()

Fetch a specific leaderboard belonging to this Instant Game.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | The name of the leaderboard. Each leaderboard for an   Instant Game must have its own distinct name. |

**Returns:** `Promise<`[`Leaderboard`](#leaderboard)`>` — A promise that resolves with the   matching leaderboard, rejecting if one is not found.

**Throws:**

- `LEADERBOARD_NOT_FOUND`
- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`
- `INVALID_OPERATION`
- `INVALID_PARAM`

**Example:**

```javascript
FBInstant.getLeaderboardAsync('my_awesome_leaderboard')
  .then(leaderboard => {
    console.log(leaderboard.getName()); // 'my_awesome_leaderboard'
  });
```

---

### postSessionScore()

Posts a player's score to Facebook. This API should only be called at the
end of an activity (example: when the player doesn't have "lives" to
continue the game). This API will be rate-limited when called too
frequently. Scores posted using this API should be consistent & comparable
across game sessions. For example, if Player A achieves 200 points in a
session, and Player B achieves 320 points in a session, those two scores
should be generated from activities where the scores are fair to be
compared and ranked against each other.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `score` | `number` | An integer value representing the player's score at   the end of an activity. |

**Example:**

```javascript
function onScore(score) {
  if (score > bestSessionScore) {
    bestSessionScore = score;
    FBInstant.postSessionScore(bestSessionScore);
  }
}
```

---

### getPlacementID()

Return the Audience Network placement ID of this ad instance.

---

### loadAsync()

Preload the ad. The returned promise resolves when the preload
completes, and rejects if it failed.

**Throws:**

- `ADS_FREQUENT_LOAD`
- `ADS_NO_FILL`
- `INVALID_PARAM`
- `NETWORK_FAILURE`

**Example:**

```javascript
FBInstant.getInterstitialAdAsync(
  'my_placement_id',
).then(function(interstitial) {
  return interstitial.loadAsync();
}).then(function() {
  // Ad loaded
});
```

---

### showAsync()

Present the ad. The returned promise resolves when user
finished watching the ad, and rejects if it failed to present or
was closed during the ad.

**Throws:**

- `ADS_NOT_LOADED`
- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `INVALID_OPERATION`
- `RATE_LIMITED`

**Example:**

```javascript
var ad = null;
FBInstant.getRewardedVideoAsync(
  'my_placement_id',
).then(function(rewardedVideo) {
  ad = rewardedVideo;
  return ad.loadAsync();
}).then(function() {
  // Ad loaded
  return ad.showAsync();
}).then(function() {
  // Ad watched
});
```

---

### getName()

The name of the leaderboard.

**Example:**

```javascript
FBInstant.getLeaderboardAsync('my_leaderboard')
  .then(function(leaderboard) {
    console.log(leaderboard.getName()); // my_leaderboard
  });
```

---

### getContextID()

The ID of the context that the leaderboard is associated with, or null if
the leaderboard is not tied to a particular context.

**Example:**

```javascript
FBInstant.getLeaderboardAsync('contextual_leaderboard')
  .then(function(leaderboard) {
    console.log(leaderboard.getContextID()); // 12345678
  });
```

```javascript
FBInstant.getLeaderboardAsync('global_leaderboard')
  .then(function(leaderboard) {
    console.log(leaderboard.getContextID()); // null
  });
```

---

### getEntryCountAsync()

Fetches the total number of player entries in the leaderboard.

**Returns:** `Promise<number>` — A unique identifier for the player.

**Throws:**

- `NETWORK_FAILURE`
- `RATE_LIMITED`

**Example:**

```javascript
FBInstant.getLeaderboardAsync('my_leaderboard')
  .then(function(leaderboard) {
    return leaderboard.getEntryCountAsync();
  })
  .then(function(count) { console.log(count); }); // 24
```

---

### getPlayerEntryAsync()

Retrieves the leaderboard's entry for the current player, or null if the
player has not set one yet.

**Returns:** `?Promise<`[`LeaderboardEntry`](#leaderboardentry)`>` — Resolves with the current leaderboard   entry for the player.

**Throws:**

- `NETWORK_FAILURE`
- `INVALID_OPERATION`
- `RATE_LIMITED`

**Example:**

```javascript
FBInstant.getLeaderboardAsync('my_leaderboard')
  .then(function(leaderboard) {
    return leaderboard.getPlayerEntryAsync();
  })
  .then(function(entry) {
    console.log(entry.getRank()); // 2
    console.log(entry.getScore()); // 42
    console.log(entry.getExtraData()); // '{race: "elf", level: 3}'
  });
```

---

### getScore()

Gets the score associated with the entry.

**Returns:** `number` — Returns an integer score value.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getScore()); // 9001
  });
```

---

### getFormattedScore()

Gets the score associated with the entry, formatted with the score format
associated with the leaderboard.

**Returns:** `string` — Returns a formatted score.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getFormattedScore()); // '90.01 meters'
  });
```

---

### getTimestamp()

Gets the timestamp of when the leaderboard entry was last updated.

**Returns:** `number` — Returns a Unix timestamp.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getTimestamp()); // 1515806355
  });
```

---

### getRank()

Gets the rank of the player's score in the leaderboard.

**Returns:** `number` — Returns the entry's leaderboard ranking.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getRank()); // 2
  });
```

---

### getExtraData()

Gets the developer-specified payload associated with the score, or null
if one was not set.

**Returns:** `?string` — An optional developer-specified payload associated with the score.

**Example:**

```javascript
leaderboard.setScoreAsync(42, '{race: "elf", level: 3}');
  .then(function(entry) {
    console.log(entry.getExtraData()); // '{race: "elf", level: 3}'
  });
```

---

### getPlayer()

Gets information about the player associated with the entry.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getPlayer().getName()); // Sally
  });
```

---

### getPhoto()

Returns a url to the player's public profile photo.

**Returns:** `?string` — Url to the player's public profile photo.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getPlayer().getPhoto()); // <photo_url>
  });
```

---

### getID()

Gets the game's unique identifier for the player.

**Returns:** `?string` — The game-scoped identifier for the player.

**Example:**

```javascript
leaderboard.setScoreAsync(9001)
  .then(function(entry) {
    console.log(entry.getPlayer().getID()); // 12345678
  });
```

---

### constructor()

Creates a new APIError instance.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `args` | [`APIErrorArgs`](#apierrorargs) | - The error arguments. |

**Returns:** `void`

---

### Types

#### Platform

Represents the current platform that the user is playing on.

---

#### SharePayload

Represents content to be shared by the user.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `intent` | `('INVITE'\|'REQUEST'\|'CHALLENGE'\|'SHARE')` | Indicates the intent of the share. |
| `image` | `string` | A base64 encoded image to be shared. |
| `media` | [`MediaParams`](#mediaparams) _(optional)_ | [IN PRIVATE BETA] Optional content for the gif   or video. |
| `text` | `string` | A text message to be shared. |
| `data` | `Object` _(optional)_ | A blob of data to attach to the share. All game   sessions launched from the share will be able to access this blob through   FBInstant.getEntryPointData(). |

---

#### MediaContent

Specify how we could get the content for the media.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `URL` | `string` | for the media that stores in the developers' server. |

---

#### MediaParams

Represents the media payload used by custom update and custom share.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Optional` | [`MediaContent`](#mediacontent) | , if provided, the content should contain   information for us to get the gif. |
| `Optional` | [`MediaContent`](#mediacontent) | , if provided, the content should contain   information for us to get the video. |

---

#### CustomUpdatePayload

Represents a custom update for FBInstant.updateAsync. Note that if localized
content is not provided, a Facebook supplied localized string will be used
for the call to action and text.

The `default` string should always be in English.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `action` | `UpdateAction` | For custom updates, this should be 'CUSTOM'. |
| `template` | `string` | ID of the template this custom update is using.   Templates should be predefined in fbapp-config.json. See   the [Bundle Config documentation][https://developers.facebook.com/docs/games/instant-games/bundle-config](https://developers.facebook.com/docs/games/instant-games/bundle-config) for   documentation about fbapp-config.json. |
| `cta` | `string \| ?`[`LocalizableContent`](#localizablecontent) _(optional)_ | Optional call-to-action button   text. By default we will use a localized 'Play' as the button text.   To provide localized versions of your own call to action, pass an object   with the default cta as the value of 'default' and another object   mapping locale keys to translations as the value of 'localizations'. |
| `image` | `string` _(optional)_ | Optional data URL of a base64 encoded image. |
| `media` | [`MediaParams`](#mediaparams) _(optional)_ | [IN PRIVATE BETA] Optional content for the gif   or video. At least one image or media should be provided in order to render   the update. |
| `text` | `string \| `[`LocalizableContent`](#localizablecontent) | A text message, or an object   with the default text as the value of 'default' and another object   mapping locale keys to translations as the value of 'localizations'. |
| `data` | `Object` _(optional)_ | A blob of data to attach to the update. All game   sessions launched from the update will be able to access this blob through   FBInstant.getEntryPointData(). Must be less than or equal to 1000   characters when stringified. |
| `strategy` | `string` _(optional)_ | Specifies how the update should be   delivered. This can be one of the following:   'IMMEDIATE' - The update should be posted immediately.   'LAST' - The update should be posted when the game session ends. The most     recent update sent using the 'LAST' strategy will be the one sent.   'IMMEDIATE_CLEAR' - The update is posted immediately, and clears any other     pending updates (such as those sent with the 'LAST' strategy).   If no strategy is specified, we default to 'IMMEDIATE'. |
| `notification` | `string` _(optional)_ | Specifies notification setting for the   custom update. This can be 'NO_PUSH' or 'PUSH', and defaults to 'NO_PUSH'.   Use push notification only for updates that are high-signal and immediately   actionable for the recipients. Also note that push notification is not   always guaranteed, depending on user setting and platform policies. |

---

#### LeaderboardUpdatePayload

Represents a leaderboard update for FBInstant.updateAsync.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `action` | `UpdateAction` | For a leaderboard update, this should be   'LEADERBOARD'.   text. By default we will use a localized 'Play Now' as the button text. |
| `name` | `string` | The name of the leaderboard to feature   in the update. |
| `text` | `string` _(optional)_ | Optional text message. If not specified, a   localized fallback message will be provided instead. |

---

#### LocalizableContent

Represents a string with localizations and a default value to fall back on.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `default` | `string` | The default value of the string to use if   the viewer's locale is not a key in the localizations object. |
| `localizations` | [`LocalizationsDict`](#localizationsdict) | Specifies what string to use   for viewers in each locale.   See https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml   for a complete list of supported locale values. |

---

#### UpdatePayload

---

#### AdInstance

Represents an instance of an ad.

---

#### Leaderboard

An Instant Game leaderboard

---

#### LeaderboardEntry

A score entry for an Instant Game leaderboard

---

#### LeaderboardPlayer

Details about the player associated with a score entry.

---

#### LocalizationsDict

Represents a mapping from locales to translations of a given string.
Each property is an optional five-character Facebook locale code of the form
xx_XX.
See https://lookaside.facebook.com/developers/resources/?id=FacebookLocales.xml
for a complete list of supported locale codes.

---

#### ErrorCode

Error codes that may be returned by the Instant Games API

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `ADS_FREQUENT_LOAD` | `string` | - Ads are being loaded too frequently. |
| `ADS_NO_FILL` | `string` | - We were not able to serve ads to the current   user. This can happen if the user has opted out of interest-based ads on   their device, or if we do not have ad inventory to show for that user. |
| `ADS_NOT_LOADED` | `string` | - Attempted to show an ad that has not   been loaded successfully. |
| `ADS_TOO_MANY_INSTANCES` | `string` | - There are too many concurrent   ad instances. Load and show existing ad instances before creating new ones. |
| `ANALYTICS_POST_EXCEPTION` | `string` | - The analytics API experienced a   problem while attempting to post an event. |
| `CLIENT_REQUIRES_UPDATE` | `string` | [Deprecated] - The client requires   an update to access the feature that returned this result. If this result   is returned on web, it means the feature is not supported by the web client  yet. Deprecated in favor of CLIENT_UNSUPPORTED_OPERATION in v5.0 and above |
| `CLIENT_UNSUPPORTED_OPERATION` | `string` | - The client does not support   the current operation. This may be due to lack of support on the client   version or platform, or because the operation is not allowed for the game   or player. |
| `OPERATION_SUPPRESSED` | `string` | - The operation was suppressed by the   platform. This may be due to user-level rate limiting, play style   restrictions, or other reasons. |
| `GLOBAL_LEADERBOARD_NOT_FOUND` | `string` | - No global leaderboard with  the requested ID was found. Either the leaderboard does not exist yet, or the  ID did not match any registered leaderboard, you can verify the leaderboard ID  in the Global Leaderboard section of the Instant Games Dashboard. |
| `IARC_CERT_NOT_FOUND` | `string` | - The requested IARC (International  Age Rating Coalition) certificate was not found. |
| `IARC_CERT_TEST_ONLY` | `string` | - This is a test IARC (International  Age Rating Coalition) operation. |
| `IARC_SUBMIT_CERT_FAILED` | `string` | - Thw IARC (International Age  Rating Coalition) certificate failed to be submitted. |
| `IARC_SUBMIT_EMAIL_FAILED` | `string` | - The developer's IARC (International Age Rating Coalition) contact email failed to be submitted. |
| `INVALID_OPERATION` | `string` | - The requested operation is invalid   or the current game state. This may include requests that violate   limitations, such as exceeding storage thresholds, or are not available in   a certain state, such as making a context-specific request in a solo   context. |
| `INVALID_PARAM` | `string` | - The parameter(s) passed to the API are   invalid. Could indicate an incorrect type, invalid number of arguments, or   a semantic issue (for example, passing an unserializable object to a   serializing function). |
| `LEADERBOARD_NOT_FOUND` | `string` | - No leaderboard with the requested   name was found. Either the leaderboard does not exist yet, or the name   did not match any registered leaderboard configuration for the game. |
| `LEADERBOARD_WRONG_CONTEXT` | `string` | - Attempted to write to a   leaderboard that's associated with a context other than the one the game is   currently being played in. |
| `MOCK_IAP` | `string` | - User is temporarily turning off Mock IAP and   switching to production flow for current purchase |
| `NETWORK_FAILURE` | `string` | - The client experienced an issue with a   network request. This is likely due to a transient issue, such as the   player's internet connection dropping. |
| `PAYMENTS_NOT_INITIALIZED` | `string` | - The client has not completed   setting up payments or is not accepting payments API calls. |
| `PENDING_REQUEST` | `string` | - Represents a rejection due an existing   request that conflicts with this one. For example, we will reject any calls   that would surface a Facebook UI when another request that depends on a   Facebook UI is pending. |
| `RATE_LIMITED` | `string` | - Some APIs or operations are being called   too often. This is likely due to the game calling a particular API an   excessive amount of times in a very short period. Reducing the rate of   requests should cause this error to go away. |
| `SAME_CONTEXT` | `string` | - The game attempted to perform a context   switch into the current context. |
| `TOURNAMENT_NOT_SHAREABLE` | `string` | - The game attempted to share   a private tournament. This is only possible for non-private tournaments. If   a score was submitted with the share call, then the score was still   submitted. |
| `UNKNOWN` | `string` | - An unknown or unspecified issue occurred. This   is the default error code returned when the client does not specify a code. |
| `USER_INPUT` | `string` | - The user made a choice that resulted in a   rejection. For example, if the game calls up the Context Switch dialog and   the player closes it, this error code will be included in the promise   rejection. |

---

#### ErrorCodeType

An Instant Games error code, one of [`ErrorCode`](#errorcode)

---

#### APIErrorArgs

Arguments for creating an API Error.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `code` | [`ErrorCodeType`](#errorcodetype) _(optional)_ | - The error code. Defaults to UNKNOWN if not provided. |
| `message` | `string` | - A message describing the error. |
| `extraData` | `string` _(optional)_ | - Optional extra data for logging purposes. |

---

#### APIError

An API Error returned by the Instant Games SDK

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `code` | [`ErrorCodeType`](#errorcodetype) | - The relevant error code |
| `message` | `string` | - A message describing the error |
| `extraData` | `string` _(optional)_ | - Optional extra data for logging purposes |

---

## FBInstant.context

Opens a context selection dialog for the player. If the player selects an

### getID()

A unique identifier for the current game context. This represents a
specific context that the game is being played in (for example, a
facebook post). The identifier will be null if game is being played
in a solo context. This function should not be called until
FBInstant.startGameAsync has resolved.

**Returns:** `?string` — A unique identifier for the current game context.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var contextID = FBInstant.context.getID();
```

---

### getType()

The type of the current game context.
POST - A facebook post.
THREAD - A chat thread.
GROUP - A facebook group.
SOLO - Default context, where the player is the only participant.

This function should not be called until FBInstant.startGameAsync has
resolved.

**Returns:** `('POST'|'THREAD'|'GROUP'|'SOLO')` — Type of the current game context.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var contextType = FBInstant.context.getType();
```

---

### isSizeBetween()

This function determines whether the number of participants in the current
game context is between a given minimum and maximum, inclusive. If one of
the bounds is null only the other bound will be checked against. It will
always return the original result for the first call made in a context in
a given game play session. Subsequent calls, regardless of arguments, will
return the answer to the original query until a context change occurs and
the query result is reset. This function should not be called until
FBInstant.startGameAsync has resolved.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `minSize` | `number` _(optional)_ | The minimum bound of the context size query. |
| `minSize` | `number` _(optional)_ | The maximum bound of the context size query. |

**Returns:** `?`[`ContextSizeResponse`](#contextsizeresponse) — An object containing minimum and maximum bounds, as well as whether the context size is within those bounds. This will be null if one or both of the supplied arguments are not valid, if we do not have a size available for the current context, or if the API is called before startGameAsync() resolves.

**Example:**

```javascript
console.log(FBInstant.context.isSizeBetween(3, 5)); (Context size = 4)
// {answer: true, minSize: 3, maxSize: 5}
```

```javascript
console.log(FBInstant.context.isSizeBetween(5, 7)); (Context size = 4)
// {answer: false, minSize: 5, maxSize: 7}
```

```javascript
console.log(FBInstant.context.isSizeBetween(2, 10)); (Context size = 3)
// {answer: true, minSize: 2, maxSize: 10}
console.log(FBInstant.context.isSizeBetween(4, 8)); (Still in same context)
// {answer: true, minSize: 2, maxSize: 10}
```

```javascript
console.log(FBInstant.context.isSizeBetween(3, null)); (Context size = 4)
// {answer: true, minSize: 3, maxSize: null}
```

```javascript
console.log(FBInstant.context.isSizeBetween(null, 3)); (Context size = 4)
// {answer: false, minSize: null, maxSize: 3}
```

```javascript
console.log(FBInstant.context.isSizeBetween("test", 5)); (Context size = 4)
// null
```

```javascript
console.log(FBInstant.context.isSizeBetween(0, 100)); (Context size = null)
// null
```

---

### switchAsync()

Request a switch into a specific context. If the player does not have
permission to enter that context, or if the player does not provide
permission for the game to enter that context, this will reject.
Otherwise, the promise will resolve when the game has switched into the
specified context.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `string` | ID of the desired context. |

**Returns:** `Promise<void>` — A promise that resolves when the game has   switched into the specified context, or rejects otherwise.

**Throws:**

- `INVALID_PARAM`
- `SAME_CONTEXT`
- `NETWORK_FAILURE`
- `USER_INPUT`
- `PENDING_REQUEST`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .switchAsync('1234567890')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 1234567890
  });
```

---

### createAsync()

Attempts to create or switch into a context between a specified player
and the current player. The returned promise will reject if the
player listed is not a Connected Player of the current player or
if the player does not provide permission to enter the new context.
Otherwise, the promise will resolve when the game has switched into the
new context.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `playerID` | `string` | ID of the player |

**Returns:** `Promise<void>` — A promise that resolves when the game has   switched into the new context, or rejects otherwise.

**Throws:**

- `INVALID_PARAM`
- `SAME_CONTEXT`
- `NETWORK_FAILURE`
- `USER_INPUT`
- `PENDING_REQUEST`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
  .createAsync('12345678')
  .then(function() {
    console.log(FBInstant.context.getID());
    // 5544332211
  });
```

---

### getPlayersAsync()

Gets an array of [`ContextPlayer`](#contextplayer) objects containing information
about active players in the current context (people who played the game in
the current context in the last 90 days). This may include the current
player.

**Returns:** `Promise<Array<@link `[`ContextPlayer`](#contextplayer)`>>` — A promise that resolves with a   list of context player objects.   NOTE: This function should not be called until FBInstant.initializeAsync()   has resolved.

**Throws:**

- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`
- `INVALID_OPERATION`

**Example:**

```javascript
var contextPlayers = FBInstant.context.getPlayersAsync()
  .then(function(players) {
    console.log(players.map(function(player) {
      return {
        id: player.getID(),
        name: player.getName(),
      }
    }));
  });
// [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}]
```

---

### getName()

Get the player's localized display name.

**Returns:** `?string` — The player's localized display name.

---

### getPhoto()

Get the player's public profile photo.

**Returns:** `?string` — A url to the player's public profile photo

---

### constructor()

Creates a new GameContext instance.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `context` | [`ContextData`](#contextdata) | - The context data to initialize with |

---

### getSize()

Returns the number of participants in this context.

**Returns:** `number|null` — The context size, or null if not available

---

### getContextSizeResponse()

Returns the response from the last context size check.

**Returns:** [`ContextSizeResponse`](#contextsizeresponse)`|null` — The context size response, or null if no check has been performed

---

### setContextSizeResponse()

Sets the response for a context size check.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `contextSizeResponse` | [`ContextSizeResponse`](#contextsizeresponse) | - The response from a context size check |

**Returns:** `void`

---

### Types

#### ContextFilter

A filter that may be applied to a Context Choose operation
'NEW_CONTEXT_ONLY' - Prefer to only surface contexts the game has not been
  played in before.
'INCLUDE_EXISTING_CHALLENGES' - Include the "Existing Challenges" section,
  which surfaces actively played-in contexts that the player is a part of.
'NEW_PLAYERS_ONLY' - In sections containing individuals, prefer people who
  have not played the game.

---

#### ContextPlayer

Represents information about a player who is in the context that the
current player is playing in.

---

#### ContextData

Data structure representing a game context.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` _(optional)_ | - The unique identifier for this context |
| `size` | `number` _(optional)_ | - The number of participants in this context |
| `type` | `ContextType` | - The type of context (e.g., SOLO, THREAD, GROUP) |

---

#### ContextSizeResponse

Response object for context size checks.
The answer field is true if the current context size is between
the minSize and maxSize values that are specified in the object,
and false otherwise.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `answer` | `boolean` | - Whether the context size is within the specified range |
| `minSize` | `number` _(optional)_ | - The minimum size specified in the check |
| `maxSize` | `number` _(optional)_ | - The maximum size specified in the check |

---

#### GameContext

Represents the social context in which the game is being played.
This class provides methods to access information about the current game context,
such as its ID, type, and size (number of participants).

---

## FBInstant.payments



### getCatalogAsync()

Fetches the game's product catalog.

**Returns:** `Promise<Array<`[`Product`](#product)`>>` — The set of products that are registered to the game.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `NETWORK_FAILURE`

**Example:**

```javascript
FBInstant.payments.getCatalogAsync().then(function (catalog) {
  console.log(catalog); // [{productID: '12345', ...}, ...]
});
```

---

### purchaseAsync()

Begins the purchase flow for a specific product.  Will immediately reject
if called before FBInstant.startGameAsync() has resolved.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `purchaseConfig` | [`PurchaseConfig`](#purchaseconfig) | The purchase's configuration details. |

**Returns:** `Promise<`[`Purchase`](#purchase)`>` — A Promise that resolves when the product is successfully purchased by the player. Otherwise, it rejects.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `INVALID_OPERATION`
- `USER_INPUT`

**Example:**

```javascript
FBInstant.payments.purchaseAsync({
  productID: '12345',
  developerPayload: 'foobar',
}).then(function (purchase) {
  console.log(purchase);
  // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}
});
```

---

### getPurchasesAsync()

Fetches all of the player's unconsumed purchases. The game must fetch the
current player's purchases as soon as the client indicates that it is ready
to perform payments-related operations, i.e. at game start. The game can then
process and consume any purchases that are waiting to be consumed.

**Returns:** `Promise<Array<`[`Purchase`](#purchase)`>>` — The set of purchases that the player has made for the game.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `NETWORK_FAILURE`

**Example:**

```javascript
FBInstant.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchase);
  // [{productID: '12345', ...}, ...]
});
```

---

### consumePurchaseAsync()

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:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `purchaseToken` | `string` | The purchase token of the purchase that should be consumed. |

**Returns:** `Promise<void>` — A Promise that resolves when the purchase has been consumed successfully.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `INVALID_PARAM`
- `NETWORK_FAILURE`

**Example:**

```javascript
FBInstant.payments.consumePurchaseAsync('54321').then(function () {
  // Purchase successfully consumed!
  // Game should now provision the product to the player
});
```

---

### onReady()

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `callback` | `Function` | The callback function to be executed when Payments are available. |

**Example:**

```javascript
FBInstant.payments.onReady(function () {
  console.log('Payments Ready!')
});
```

---

### Types

#### Product

Represents a game's product information.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `title` | `string` | The title of the product |
| `productID` | `string` | The product's game-specified identifier |
| `description` | `string` _(optional)_ | The product description |
| `imageURI` | `string` _(optional)_ | A link to the product's associated image |
| `price` | `string` | The price of the product |
| `priceCurrencyCode` | `string` | The currency code for the product |

---

#### Purchase

Represents an individual purchase of a game product.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `developerPayload` | `string` _(optional)_ | A developer-specified string, provided during the purchase of the product |
| `paymentID` | `string` | The identifier for the purchase transaction |
| `productID` | `string` | The product's game-specified identifier |
| `purchaseTime` | `string` | Unix timestamp of when the purchase occurred |
| `purchaseToken` | `string` | A token representing the purchase that may be used to consume the purchase |
| `signedRequest` | `SignedPurchaseRequest` | Server-signed encoding of the purchase request |

---

#### SignedPurchaseRequest
A signature to verify this object indeed comes from Facebook. The string is
base64url encoded and signed with an HMAC version of your App Secret, based
on the OAuth 2.0 spec.

You can validate it with the following 4 steps:

Split the signature into two parts delimited by the '.' character.
Decode the first part (the encoded signature) with base64url encoding.
Decode the second part (the response payload)  with base64url encoding,
  which should be a string representation of a JSON object that has the
  following fields:
* algorithm - always equals to HMAC-SHA256
* issued_at - a unix timestamp of when this response was issued
* purchase_token - A token representing the purchase that may
     be used to consume the purchase
* product_id - The product's game-specified identifier
* app_id - The game's application ID
* purchase_time - Unix timestamp of when the purchase occurred
* payment_id - The identifier for the purchase transaction
* developer_payload - A developer-specified string, provided
     during the purchase of the product
* is_consumed - Whether the purchase has been consumed by the player.
Hash the whole response payload string using HMAC SHA-256 and your app
  secret and confirm that it is equal to the encoded signature.
You may also wish to validate the issued_at timestamp in the response
  payload to ensure the request was made recently.

Signature validation should only happen on your server. Never do it on the
client side as it will compromise your app secret key.

---

#### PurchaseConfig

The configuration of a purchase request for a product registered to the game.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `productID` | `string` | The identifier of the product to purchase |
| `developerPayload` | `string` _(optional)_ | An optional developer-specified payload, to be included in the returned purchase's signed request. |

---

#### SignedPurchaseRequest
A signature to verify this object indeed comes from Facebook. The string is
base64url encoded and signed with an HMAC version of your App Secret, based
on the OAuth 2.0 spec.

You can validate it with the following 4 steps:

Split the signature into two parts delimited by the '.' character.
Decode the first part (the encoded signature) with base64url encoding.
Decode the second part (the response payload)  with base64url encoding,
  which should be a string representation of a JSON object that has the
  following fields:
* algorithm - always equals to HMAC-SHA256
* issued_at - a unix timestamp of when this response was issued
* app_id - The game's application ID
* is_consumed - Whether the purchase has been consumed by the player.
* payment_action_type - The current status of the purchase
* payment_id - The identifier for the purchase transaction
* product_id - The product's game-specified identifier
* purchase_price - Contains the local amount and currency associated with
     the purchased item
* purchase_token - A token representing the purchase that may
     be used to consume the purchase
* purchase_time - Unix timestamp of when the purchase occurred
* developer_payload - A developer-specified string, provided
     during the purchase of the product
Hash the whole response payload string using HMAC SHA-256 and your app
  secret and confirm that it is equal to the encoded signature.
You may also wish to validate the issued_at timestamp in the response
  payload to ensure the request was made recently.

Signature validation should only happen on your server. Never do it on the
client side as it will compromise your app secret key.

---

## FBInstant.player



### getID()

A unique identifier for the player. A Facebook user's player ID will
remain constant, and is scoped to a specific game. This means that
different games will have different player IDs for the same user.
This function should not be called until FBInstant.initializeAsync() has
resolved.

**Returns:** `?string` — A unique identifier for the player.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var playerID = FBInstant.player.getID();
```

---

### getSignedPlayerInfoAsync()

Fetch the player's unique identifier along with a signature that verifies
that the identifier indeed comes from Facebook without being tampered with.
This function should not be called until FBInstant.initializeAsync() has
resolved.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `requestPayload` | `string` _(optional)_ | A developer-specified payload to include in the signed response. |

**Returns:** `Promise<`[`SignedPlayerInfo`](#signedplayerinfo)`>` — A promise that resolves with a [`SignedPlayerInfo`](#signedplayerinfo) object.

**Throws:**

- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
FBInstant.player.getSignedPlayerInfoAsync('my_metadata')
  .then(function (result) {
    // The verification of the ID and signature should happen on server side.
    SendToMyServer(
      result.getPlayerID(), // same value as FBInstant.player.getID()
      result.getSignature(),
      'GAIN_COINS',
      100);
  });
```

---

### canSubscribeBotAsync()

Returns a promise that resolves with whether the player can subscribe to
the game bot or not.

**Returns:** `Promise<boolean>` — Whether a player can subscribe to the game bot or not. Developer can only call subscribeBotAsync() after checking canSubscribeBotAsync(), and the player will only see this bot subscription dialog once every 90 days for a given game.

**Throws:**

- `RATE_LIMITED`
- `INVALID_OPERATION`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
// This function should be called before FBInstant.player.subscribeBotAsync()
FBInstant.player.canSubscribeBotAsync().then(
  can_subscribe => console.log(can_subscribe)
);
// 'true'
```

---

### subscribeBotAsync()

Request that the player subscribe the bot associated to the game. The API
will reject if the subscription fails - else, the player will subscribe the
game bot.

**Returns:** `Promise` — A promise that resolves if player successfully subscribed to the game bot, or rejects if request failed or player chose to not subscribe.

**Throws:**

- `INVALID_PARAM`
- `PENDING_REQUEST`
- `CLIENT_REQUIRES_UPDATE`

**Example:**

```javascript
FBInstant.player.subscribeBotAsync().then(
  // Player is subscribed to the bot
).catch(function (e) {
  // Handle subscription failure
});
```

---

### getName()

The player's localized display name. This function should not be called
until FBInstant.initializeAsync() has resolved.

**Returns:** `?string` — The player's localized display name.

**Example:**

```javascript
// This function should be called after FBInstant.initializeAsync()
// resolves.
var playerName = FBInstant.player.getName();
```

---

### getPhoto()

A url to the player's public profile photo. The photo will always be a
square, and with dimensions of at least 200x200. When rendering it in the
game, the exact dimensions should never be assumed to be constant. It's
recommended to always scale the image to a desired size before rendering.
The value will always be null until FBInstant.initializeAsync() resolves.

WARNING: Due to CORS, using these photos in the game canvas can cause it
to be tainted, which will prevent the canvas data from being extracted.
To prevent this, set the cross-origin attribute of the images you use to
'anonymous'.

**Returns:** `?string` — Url to the player's public profile photo.

**Example:**

```javascript
var playerImage = new Image();
playerImage.crossOrigin = 'anonymous';
// This function should be called after FBInstant.initializeAsync()
// resolves.
playerImage.src = FBInstant.player.getPhoto();
```

---

### getDataAsync()

Retrieve data from the designated cloud storage of the current player.
Please note that JSON objects stored as string values would be returned back as JSON objects

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `keys` | `Array<string>` | An array of unique keys to retrieve data for. |

**Returns:** `Promise.<Object>` — A promise that resolves with an   object which contains the current key-value pairs for each key   specified in the input array, if they exist.

**Throws:**

- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.player
  .getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
     console.log('data is loaded');
     var achievements = data['achievements'];
     var currentLife = data['currentLife'];
  });
```

---

### setDataAsync()

Set data to be saved to the designated cloud storage of the current
player. The game can store up to 1MB of data for each unique player.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `Object` | An object containing a set of key-value pairs   that should be persisted to cloud storage. The object must contain   only serializable values - any non-serializable values will cause   the entire modification to be rejected. |

**Returns:** `Promise` — A promise that resolves when the input values are set.   NOTE: The promise resolving *does not* necessarily mean that the input   has already been persisted. Rather, it means that the data was valid   and has been scheduled to be saved. It also guarantees that all   values that were set are now available in player.getDataAsync.

**Throws:**

- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `PENDING_REQUEST`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(function() {
    console.log('data is set');
  });
```

---

### flushDataAsync()

Immediately flushes any changes to the player data to the designated
cloud storage. This function is expensive, and should primarily be used
for critical changes where persistence needs to be immediate and known
by the game. Non-critical changes should rely on the platform to persist
them in the background.
NOTE: Calls to player.setDataAsync will be rejected while this function's
result is pending.

**Returns:** `Promise` — A promise that resolves when changes have been   persisted successfully, and rejects if the save fails.

**Throws:**

- `INVALID_PARAM`
- `NETWORK_FAILURE`
- `PENDING_REQUEST`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
FBInstant.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(FBInstant.player.flushDataAsync)
  .then(function() {
    console.log('Data persisted to FB!');
  });
```

---

### getConnectedPlayersAsync()

Fetches an array of ConnectedPlayer objects containing information about
active players (people who played the game in the last 90 days) that are
connected to the current player.

**Returns:** `Promise<Array<`[`ConnectedPlayer`](#connectedplayer)`>>` — A promise that resolves with a   list of connected player objects.   NOTE: This function should not be called until FBInstant.initializeAsync()   has resolved.

**Throws:**

- `NETWORK_FAILURE`
- `CLIENT_UNSUPPORTED_OPERATION`

**Example:**

```javascript
var connectedPlayers = FBInstant.player.getConnectedPlayersAsync()
  .then(function(players) {
    console.log(players.map(function(player) {
      return {
        id: player.getID(),
        name: player.getName(),
      }
    }));
  });
// [{id: '123456789', name: 'Paul Atreides'}, {id: '987654321', name: 'Duncan Idaho'}]
```

---

### constructor()

Creates a new ConnectedPlayer instance.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `playerID` | `string` | - The ID of the connected player. |

---

### getPlayerID()

Get the id of the player.

**Returns:** `string` — The ID of the player

**Example:**

```javascript
FBInstant.player.getSignedPlayerInfoAsync()
  .then(function (result) {
    result.getPlayerID(); // same value as FBInstant.player.getID()
  });
```

---

### getSignature()

A signature to verify this object indeed comes from Facebook. The string is
base64url encoded and signed with an HMAC version of your App Secret, based
on the OAuth 2.0 spec.

You can validate it with the following 5 steps:

1. Split the signature into two parts delimited by the '.' character.
2. Decode the first part (the encoded signature) with base64url encoding.
3. Decode the second part (the response payload) with base64url encoding,
  which should be a string representation of a JSON object that has the
  following fields:
algorithm - always equals to HMAC-SHA256
issued_at - a unix timestamp of when this response was issued.
player_id - unique identifier of the player.
request_payload - the requestPayload string you specified when calling
      FBInstant.player.getSignedPlayerInfoAsync.
4. Hash the whole response payload string using HMAC SHA-256 and your app
  secret and confirm that it is equal to the encoded signature.
5. You may also wish to validate the issued_at timestamp in the response
  payload to ensure the request was made recently.

Signature validation should only happen on your server. Never do it on the
client side as it will compromise your app secret key.

**Returns:** `string` — The signature string.

**Example:**

```javascript
FBInstant.player.getSignedPlayerInfoAsync()
  .then(function (result) {
    result.getSignature();
    // Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ
  });
```

---

### Types

#### ConnectedPlayer

Represents information about a player who is connected to the current player.

---

#### SignedPlayerInfoData

Data structure containing player information and signature.

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `playerID` | `string` | - The unique identifier of the player. |
| `signature` | `string` | - The signature to verify the player information. |

---

#### SignedPlayerInfo

Represents information about the player along with a signature to verify that
it indeed comes from Facebook.

---