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": "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": "", /* 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 are all relative to the table, which has its own accumulating timer. Rewards Tables configured with multiple pages will all share state between them.

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




The game name displayed to users in the awards popup. If not specified, will fall back to the name of the app.



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



Default value: 600

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



Default value: 7200

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



Default value: 3600, Minimum value: 1

p50_drop_time represents the number of seconds after min_time whereupon 50% of the people watching will receive a drop.



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.



Default value: false

When no time carryover is enabled, time will not continue to accrue after a reward appears until the min_interval is complete.

drop_art_asset, open_art_asset


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


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



Default value: true

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



Default value: true

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



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






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



Default value: 1

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



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



Default value: unset

Limit the number of rewards of this specific item to the value, if given. Unlimited if unset.

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:<API_VERSION>/me/game_items
  ?access_token=<ACCESS TOKEN>

Example query result:

    “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:<API_VERSION>/me/game_items
    ?access_token<ACCESS TOKEN>
    &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:<API_VERSION>/<USERID>/game_items
    ?access_token=<ACCESS TOKEN>
    &ext_id=<ITEM DEFINITION ID>

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.