In-stream Rewards

Viewers and streamers are critical to the success of your game.

In-stream Rewards allows you to reward your players for watching game video streams on Facebook from Pages you designate.

This exciting feature helps players build community and increases player engagement.

In-stream rewards are data-driven; you are always in charge of your own game's economy.

At a high level, the flow looks like this:

  1. Configure your application for In-stream Rewards.
  2. All live videos tagged with your game that are streaming to the Pages you selected are eligible for In-stream Rewards.
  3. Live video viewers see award popups based on your configuration and claim the reward by pressing the claim button.
  4. The player links his or her game account to Facebook using Facebook Login. Unlinked users can claim rewards in the UI but will not receive them until using Facebook Login into the appropriate application.
  5. The next time the player opens your game, the game checks for the presence of pending awards and then awards the user with their items.

Technical Integration

As In-stream Rewards is under closed beta, please send us the Facebook App ID for whitelisting.

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_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 */
    "max_stack_size": 1, /* optional */
    "auto_stack": false, /* optional, currently unimplemented */
    "tradable": true,    /* optional, currently unimplemented */
    "hidden": false,     /* optional, currently unimplemented */
    "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": 3600,
  "min_interval": 64800,
  "drop_art_asset": "https://www.facebook.com/example.png",
  "open_art_asset": "https://www.facebook.com/example.png",
  "name_localized": {
    "en_US": "My Game"
  },
  "chest_name_localized": {
    "en_US": "Chest"
  },
  "developer_only": false,
  "enabled": true,
  "countries_allowed": ["US", "AU", "NZ"],
  "countries_blocked": ["DE", "FR"],
  "approved_app_ids": [8675309],
  "drops": [
  {
    "item_id": 1,
    "quantity": 1,
    "chance": 90
  },
  ...
  ]
}

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.


Explanation of fields

FieldRepresents

name_localized

map<string,string>

A descriptive name of the type of drop the user is getting

chest_name_localized

map<string,string>

A description of the container the viewer claims (e.g., "Chest")

min_time

int

Default value: 600

The minimum amount of time in seconds that the viewer must watch before receiving a drop

max_time

int

Default value: 7200

The maximum amount of time in seconds that the viewer must watch before receiving a drop

p50_drop_time

int

Default value: 3600, Minimum value: 1

A user has a 50% chance of receiving a drop every p50_drop_time seconds

min_interval

int

The number of seconds of calendar time after a drop is received before the user is eligible for another

Instead of a one reward a day rule, we recommend using a value slightly less than a day (such as 72000 for 20 hours) to account for viewer eligibility from the tail end of today's broadcast to the beginning of tomorrow's. Viewers can still accumulate time, up to the max_time in credit, for their next drop while within the min_interval.

drop_art_asset, open_art_asset

string

A URL to a 300x300 png with transparency enabled which is displayed to the watcher when a drop occurs or when it is claimed

countries_allowed, countries_blocked

string[]

A list of two-letter country codes where this table is active or disabled. Useful for gating rewards to specific countries

approved_app_ids

int[]

Default value: An array containing only the id of the app you upload it to.

Enables rewards on live videos tagged with the specified app id. Pass an empty array to enable rewards for all live video broadcast from the specified Pages. All apps specified should be within the same business.

enabled

bool

Default value: true

Whether or not the rewards table is currently active. Disabled tables do not accumulate watch time.

developer_only

bool

Default value: true

If true, only viewers with developer or admin roles receive drops

page_ids

int[]

A list of page ids to enable for this table. Pages specified in the UI, if any, will overwrite this field.

drops

object[]

Field
Represents

item_id

int

The corresponding entry in the rewards table

Choose something such as a database ID or SKU that you can easily map back to the corresponding item in your game

quantity

int

Default value: 1

The number of items to drop (for example, 500 coins)

chance

int

The weighted chance of selection relative to the other items in the table


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

When the viewer launches your game, you can check the status, and detect whether their In-stream Rewards have already been claimed with an HTTP GET:

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

Example query result:

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

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?action=mark&item_id=<ITEM ID>

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