Build

Overview

You will have to use Instant Games v8.0+ in this new model.

We are publishing a new model of permissions for Instant Games on Facebook. In this model, games will no longer have access to sensitive user information, primarily names and profile pictures of the current user or their friends. Instead, Meta will control the rendering of this information in separate iframe containers (called overlay views) that games will control separately, without having access to the data within.

This will remove the Terms Of Service blocking screen for new players when they play these games, thus enabling instant play.

Overall structure

Instant games will no longer have direct access to sensitive user data . Instead, Meta will handle the rendering of UI involving user data on behalf of Games through XML configuration files.

The rendering logic for this user information will be executed on a different iFrame.

Supported Files

Games can specify the files for the rendering layout of the Overlay Views in the game bundles. The current list of file formats supported in Overlay Views are:

  • XML (to specify components and styling)
  • PNG/JPEG (local image files to render)
  • TTF (Font files)
  • CSS (Cascading Style Sheet File for styling)

Javascript is not allowed!

Meta will translate these XML files into the corresponding HTML with CSS to render the declared components.

Lifecycle for Overlay views

  1. The game will call the Instant Games SDK API to create an OverlayView object using the API: FBInstant.views.createOverlayView
  2. The overlay view object is returned which contains a reference to the iFrame element.
  3. The game attaches this iFrame element to its DOM, which initializes the logic to parse the XML.
  4. Once the iFrame has all the data and styling ready, it lets the game know that it's ready to render using the initialization callback provided in FBInstant.views.createOverlayView.
  5. The game can then call show/dismiss on the overlay view to show or hide it.

Data in Overlay Views

Data in overlay views comes from two main sources:

  • Map of key-value pairs supplied by the game on creation/update of the overlay views
  • User data retrieved from Meta servers such as profile picture, name and friends list, etc.

Key-value pairs supplied

Data can be supplied in a JSON object to the creation/update APIs (described in the Instant Games SDK section). For example, you can provide the following to the APIs

{
  score: 10
}

This can then be referenced with the curly braces syntax in your overlay view XML files with {{score}}

User data retrieved from Meta

You can query user data using curly braces and special keys. For example, to request the user’s profile picture, you would mention the key {{FBInstant.player.photo}}. The complete list of current resolvable keys is as follows

  • {{FBInstant.player.id}}
  • {{FBInstant.player.name}}
  • {{FBInstant.player.photo}}
  • {{FBInstant.player.connectedPlayers}}: List of connected players
  • {{itemName.id}} (Note that itemName would be a key you define in the For tag)
  • {{itemName.name}}
  • {{itemName.photo}}
  • {{FBInstant.context.id}}
  • {{FBInstant.context.participants}}: List of context participants
  • {{itemName.id}} (Note that itemName would be a key you define in the For tag)
  • {{itemName.name}}
  • {{itemName.photo}}
  • {{FBInstant.player.data}}: Player data that is stored using FBInstant.player.setDataAsync(). You can further query this data using keys that exist in your JSON blob. For example, if you stored using the call FBInstant.player.setData({level: 123}), then you can reference it in the overlay view by {{FBInstant.player.data.level}}
  • {{FBInstant.players[PLAYER_ID].(name|photo|data)}}: Get a specific player's data in an overlay view using this key (will be preferred over the current {{FBInstant.player.friends[PLAYER_ID]}} key which only works for friends)

Player Identification

There are two types of player identification supported in this model

  1. Player ID
    • Retrievable with getID or getSignedPlayerInfoAsync
    • A unique identifier of the player
    • Player ID is the default player identification that should be used for all use cases, and will always be supported for all users.
  2. App Scoped User ID
    • Retrievable with getASIDAsync or getSignedASIDAsync
    • A unique identifier for the player. This is the standard Facebook Application-Scoped ID which is used for all Graph API calls. If your game shares an AppID with a native game this is the ID you will see in the native game too.
    • Can be used to connect past game data/ native game data associated with the user.
    • App Scoped User ID will only be retrievable for users migrating over from your canvas app or for users that had previously accepted Terms of Service for your game. Retrieval of App Scoped User ID will not work for new users onboarded to the game only in Zero Permissions environment.

Differences in APIs in Zero Permissions model (v8.0+) vs regular Instant games