In-stream Rewards

Technical Integration

• Configuring your app
• Detecting Linked Accounts
• Collecting Rewards in-game
• Handling Multiple Games

Configuring your In-stream Rewards

JSON files specify the list of potential items as well as control their frequency and interval.

Items Definitions

The item definitions table is an array of item objects that allow you to configure each in-game item that can appear as a reward.

Example item_defs.json file:

{
  "items": [
  {
    "item_id": 1,
    "name": "Crowbar", /* Only displayed in the UI tool */
    "name_localized": {
      "en_US": "Crowbar"
    },
    "description_localized": {
      "en_US": "A rusty crowbar"
    },
    "unique": false,     /* optional, reward will not be shown to users who already have an instance of the item in their inventory */
    "rarity": 1,         /* currently unimplemented */
    "art_asset": "https://www.facebook.com/1.png", /* 300x300png with transparency */
   },
   ...
]}

Rewards tables

The rewards table allows you to configure the drop intervals and rarity for items. You can create multiple configurations as necessary to have different tiers of drops for the same page, or have different frequencies and viewers for a particular announcement, event, or Facebook Creator.

The time fields referenced below are all relative to the table, which has its own accumulating timer. Rewards Tables configured with multiple pages will all share state between them.

Example rewards_tables.json file:

{
  "min_time": 600,
  "max_time": 7200,
  "p50_drop_time": 600,
  "min_interval": 64800,
  "drop_art_asset": "https://www.facebook.com/example.png",
  "name_localized": {
    "en_US": "My Cool Game"
  },
  "chest_name_localized": {
    "en_US": "Chest"
  },
  "developer_only": false,
  "enabled": true,
  "countries_allowed": ["US", "AU", "NZ"],
  "countries_blocked": ["DE", "FR"],
  "drops": [
  {
    "item_id": "1",
    "quantity": 1,
    "chance": 90,
    "max_drops": 2000
  },
  ...
  ]
}

Updates to the table will affect viewers currently watching, although it can take up to a minute for those changes to take affect. You could take advantage of this behavior to give out an additional reward to everyone watching a special event, for example, by creating a new table with a min_time of 1, max_time of 2, p50_drop_time of 1, and a reasonable min_interval.

More than one table can be active at once if, for example, you would like to tier different levels of drops at different intervals of watch time. The time accrues for each individual table independently from one another.

Explanation of fields

Upload your JSON files with the Developer Dashboard tool

Add the product called "Game Add-ins" to your Facebook App. One of the sub-items will be called "In-stream rewards". Click on that item to upload your files and associate pages with your rewards tables. The tool requires you to have permissions over the relevant pages; contact us to enable rewards on third party pages.

You can upload reward_items.json here:

And you can upload stream_rewards.json here:

Detecting Linked Accounts

You should prompt the Login flow in your game to connect the viewer's gaming account to a Facebook account:

It's a good idea to save a long-lived token to your server to make these calls from your service layer to avoid trusting the game client.

Reading the Reward status

Each time the viewer launches your game with Facebook Login, you can check the status, and detect whether their In-stream Rewards have already been claimed through the Graph API. The access token is the one acquired after completing a user completes the Facebook Login flow in your game. With that you can query a list of pending rewards with an HTTP GET:

https://graph.facebook.com/<API_VERSION>/me/game_items
  ?access_token=<ACCESS TOKEN>
  [&status=active]

Example query result:

{
  “data”:[
  {
    “id”: 738246326216363,
    “item_def”: 1,
    “count”: 1,
    “status”: “ACTIVE”,
  },
  {
    “id”: 738246384374434,
    “item_def”: 2,
    “count”: 1,
    “status”: “MARKED”,
  }]
}

The optional status parameter can filter the results based on the specified status. The unique IDs of the Rewards are returned in the result to allow your game to differentiate between item instances.

Collecting Rewards in-game

When you detect a new unclaimed drop, you can consume the reward with an HTTP POST:

https://graph.facebook.com/<API_VERSION>/me/game_items
    ?access_token<ACCESS TOKEN>
    &action=mark
    &item_id=<ITEM ID>  // from game_items GET

After adding the reward to your game's inventory system, it's a good idea to present it in-game:

When they click a collect button, you can consume the reward with an HTTP POST:

This will mark the item specified via item_id with the state “marked” so you can identify which items are already collected by your player.

An item can also be awarded to a user for testing or to synchronize their game inventory with Facebook for the purpose of excluding unique items they may have previously acquired. Use the app access token and HTTP POST to:

https://graph.facebook.com/<API_VERSION>/<USERID>/game_items
    ?access_token=<ACCESS TOKEN>
    &action=drop
    &ext_id=<ITEM DEFINITION ID>
    &quantity=1

Handling multiple games

For developers or publishers with multiple shipped games, account login, including the link to Facebook, often happens at the business level. In this case, a User Access Token contains the application information of the authenticating application and not the game. Here is how to setup In-Stream Rewards to handle this situation:

1. Create an application for each game if you do not already have one.
2. Claim your apps in Business Manager. The apps must all connect to the same Business as the app that the user linked to Facebook.
3. Append the app_id parameter to your /game_items GET and POST requests, specifying the app id of your game's application.