At a high level, the flow looks like this:
|
As In-stream Rewards is under closed beta, please send us the Facebook App ID for whitelisting.
JSON files specify the list of potential items as well as control their frequency and interval.
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.
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 */ }, ... ]}
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.
Field | Represents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
map<string,string> | The game name displayed to users in the awards popup. If not specified, will fall back to the name of the app. | ||||||||||
map<string,string> | A description of the container the viewer claims (e.g., "Chest") | ||||||||||
int | Default value: 600 The minimum amount of time in seconds that the viewer must watch before receiving a drop | ||||||||||
int | Default value: 7200 The maximum amount of time in seconds that the viewer must watch before receiving a drop | ||||||||||
int | Default value: 3600, Minimum value: 1 p50_drop_time represents the number of seconds after | ||||||||||
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 | ||||||||||
bool | Default value: false When no time carryover is enabled, time will not continue to accrue after a reward appears until the | ||||||||||
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 | ||||||||||
string[] | A list of two-letter country codes where this table is active or disabled. Useful for gating rewards to specific countries | ||||||||||
bool | Default value: true Whether or not the rewards table is currently active. Disabled tables do not accumulate watch time. | ||||||||||
bool | Default value: true If true, only viewers with developer or admin roles receive drops | ||||||||||
int[] | A list of page ids to enable for this table. Pages specified in the UI, if any, will overwrite this field. | ||||||||||
object[] |
|
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:
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.
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.
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
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:
app_id
parameter to your /game_items
GET
and POST
requests, specifying the app id of your game's application.