Legacy Drops Guide

Introduction

Drops enables you to grant in-game rewards to the Twitch community for watching streams of your game. For example, you can reward viewers with exclusive in-game content, or distribute beta keys to viewers as part of your announcement event. These rewards bring viewers closer to your game, ultimately helping you acquire new players or re-engaging your existing player base.

There are several visual indicators of Drops:

• The browse directory (categories) page indicates whether Drops are available to all channels streaming the game. If your Drops campaign is available only to white-listed channels, no indicator is displayed. 
• The game directory (category) page indicates whether Drops are available to all channels broadcasting the game. If your Drops campaign is available only to white-listed channels, no indicator is displayed.
• If a channel is Drops-enabled, the channel page tells viewers whether:
  • They are eligible (all set up) to receive Drops.
  • They must create a Twitch account or link their Twitch and game accounts, to be eligible for Drops.
  • The broadcaster has opted out of Drops.

Drops functionality is powered by:

• Twitch Authorization, which allows your players to log in to other applications with their Twitch credentials.
• The Twitch Viewer Heartbeat Service (VHS), a data-reporting service that sends JSON data about a user’s viewing activity to an HTTPS endpoint you host. You can use the incoming identities to select users for content entitlements and reward them as desired. To know which customers are watching your game on Twitch, your website or the game must integrate with Twitch Authorization.

Set up Drops for your organization

To use Twitch Drops, you must have a Twitch Organization and have claimed a game on Twitch. If this is your first time using the Twitch developer site, register your organization and game with Twitch. See the Organizations Guide for more information.

Step 1: Set up Twitch Authentication

Follow the steps in the Authentication Guide to:

• Obtain a clientID from your personal console (Under Applications - This module is currently not supported in your organization console.). Registration allows you to obtain a client ID and client secret. Retain your Client ID.
• Get a user access token. When you authenticate on behalf of a user, you are granted an access token that uniquely identifies to us your client and the Twitch user. This includes specifying scopes, the permissions you are allowed on behalf of an authorized Twitch user. To use the VHS endpoint, specify the viewing_activity_read scope when you request a token. Securely store this token.
• Send the access token in your API requests to authenticate.

Step 2: Create an endpoint to receive VHS data

Create an HTTPS endpoint to receive the VHS data. You use the posted data and incoming identities to select viewers and broadcasters for in-game rewards.

After we POST VHS data, we expect a 2XX status code in response. If one of these response codes is not returned, we retry up to three times, with a 15-second timeout. If the call and three retries fail, we stop sending that report (and all subsequent reports for that minute of time) and try again in the next minute, with the data at that time.

Step 3: Manage Drops settings

1. Log onto the Twitch Developer Console.
2. Switch the console for the organization you wish to manage your Drops. Click View All within drops.
3. Click Drops Settings, then enter the requested fields for VHS configuration:
   • Client ID — From the authentication step above.
   • Endpoint — Your HTTPS endpoint for receiving the VHS heartbeats.
4. Save your changes.
5. If you check the checkbox that says”Send periodic VHS reports…”, VHS will emit heartbeats. (Uncheck this box if you want to stop receiving heartbeats.)
   Save your changes.
6. Click Submit.

Step 4: Request VHS data from users

Once users, both viewers and broadcasters, link their Twitch and game accounts, use the Create User Connection to Viewer Heartbeat Service (VHS) endpoint to create a VHS mapping and request VHS data.

Broadcasters must go through the same linking process. For broadcasters who have not linked their Twitch and game accounts, heartbeats are not sent and as a result, those broadcasters’ viewers will not receive Drops.

That’s it, you’re set up for Drops!

Viewer Heartbeat Service (VHS) data

Twitch will POST the VHS data to your designated HTTPS endpoint every minute, on each reported channel. The data is provided in JSON format. It is a fault-tolerant system that retries if there is an error in data transport.

Each minute, for each developer, we start sending reports. Reports are sent one channel at a time. We continue until we receive, from the developer’s endpoint, a success response, a failed response, or a timeout.  The timeout is set for 15 seconds (so an initial try up to three re-tries take one minute). If a given channel fails all four times in a given minute, we stop sending reports until the next minute.

A channel is a Twitch stream that has a broadcaster and one or more viewers. We only broadcast live data. Moreover, we only send data if the broadcaster has established an account link and there is at least one viewer who has also established an account link. Those are the criteria for selecting a channel for reporting. You can specify which channels will inform users of Drops becoming available, but VHS data will be available for all channels that have an established account link.

There is a unique JSON object for each broadcaster. Here is a sample JSON post:

{
    "broadcaster": "broadcaster-id-0000",
    "broadcast_id": 27388295120,
    "viewers": 6,
    "viewer_list": [ "viewer-id-0000", "viewer-id-0001", ...],
    "game": "GameName",
    "version": 1,
    "id": "f0bacda2-0e39-47ca-8bf0-44e3ab32be08",
    "time": "2006-01-02T15:04:05Z07:00",
    "retries": 0
}

Where:

• viewers is the number of linked viewers in the channel of the similarly linked broadcaster.
• viewer_list is an array of viewer ID strings, as requested by you when the VHS request for data is made in step 5 above.
• The IDs sent for broadcasters and viewers are their in-game IDs. 
• id is a random string generated for request differentiation (to avoid processing the same information twice) .
• retries is the number of times Twitch has re-tried the POST if there was an error in earlier attempts. Note that if retries is zero, it is omitted from the POST. That is, for the first call, the POST won’t have the retries field, while in subsequent POSTs, retries will be set to 1, 2, or 3.

Also see the reference documentation for the associated endpoints:

• Create User Connection to Viewer Heartbeat Service (VHS)
• Check User Connection to Viewer Heartbeat Service (VHS)
• Delete User Connection to Viewer Heartbeat Service (VHS)
• Create Entitlement Grants Upload URL

Test Drops VHS connectivity

To test whether you are receiving VHS heartbeats from Twitch:

1. Create a channel. (If you have a Twitch account, you already have a channel.) To access your Twitch channel, log in to your Twitch Profile page. If you do not have an account, it’s easy to create one.
2. Specify channel settings. Go to your channel dashboard (https://www.twitch.tv/<username>/dashboard). Select Live > Stream Information. Set the Title, Language, and Game, adding information for the game for which you are testing Drops VHS.
3. Link your channel, by going through the same OAuth flow that your viewers will go through.
4. Start streaming to your channel. After 5-10 minutes, you should start receiving heartbeats on your VHS endpoint.

Managing Drops campaigns

During a campaign, unlinked viewers watching a linked broadcaster of your game will receive a notification that they are eligible for Drops. Clicking the notification will navigate them to your connection page.

The major steps in using drops campaigns are creating the campaigns themselves, followed by the rewards you will distribute during the campaign.

Creating and editing Drops campaigns

A Drops Campaign specifies the period of time that you will distribute a set of in-game rewards to Twitch viewers who watch a stream for longer than 5 minutes. 

To setup a drops campaign:

1. Go to your developer console: log into the developer site (https://dev.twitch.tv) and click Your Console, or go to https://dev.twitch.tv/console.
2. Click Drops > + Create a Drops Campaign.
3. Enter the requested fields:
   • Campaign Image: This image will be shown to streamers to summarize the campaign, and will also be used as the default image when multiple rewards are present without images associated to them.
   • Campaign Name: This name will be present to streamers and viewers.
   • Start Date Time and End Date Time (in UTC) for your campaign.
   • Games to which the campaign will apply. You are only allowed to specify games that are claimed by your organization.
   • Drops Connection URL, where unlinked viewers will be sent to create an identity connection with your game’s identity system.
4. When all fields have been entered, the Submit button is enabled. Click it to Click it to create the campaign with the selected items, or click Cancel.

After you save your new campaign, you will be able to:

• Manage the rewards you distribute to viewers during the campaign
• Allowlist channels that would have access to distribute drops during this campaign.

Once your campaign is live, there are several visual indicators of Drops visible on Twitch:

• The browse directory (categories) page indicates whether Drops are available to all channels streaming the game. (If your Drops campaign is available only to white-listed channels, no indicator is displayed. )
• The game directory (category) page indicates whether Drops are available to all channels broadcasting the game. (If your Drops campaign is available only to white-listed channels, no indicator is displayed).
•  If a channel is Drops-enabled, the channel page tells viewers whether:
  • They are eligible (all set up) to receive Drops.
  • They must create a Twitch account or link their Twitch and game accounts, to be eligible for Drops.
  • The broadcaster has opted out of Drops.

Create and edit Rewards using the Rewards Manager

Drops Rewards (formerly, items) are the in-game content or keys you will entitle users to who watch any streams with Drops enabled. Each reward has a unique Reward ID that you can reference when entitling Twitch users who have linked their identity to your game’s identity system. To create rewards, you can do so after you’ve created a campaign directly within the Rewards tab, or via the Reward Manager using the steps below.

1. Login to your organization’s console on dev.twitch.tv/console.
2. Click Drops > Reward Manager > + Add New Reward.
3. Enter the requested fields:
   • An Item Image (120x120 pixels) representing the Drop. Note that to support retina displays, images are converted down to 80x80, which is loaded into the page in a 40x40 slot.
   • One or more Localized Item Names.
   • Default Locale for Item Name, used if no value is provided in the viewer’s locale.
4. When all fields have been entered, the Save Reward button is enabled. Click it to create the item, or click Cancel.

Manage access to your Campaigns

Within a Drops Campaign, you can allowlist channels to be eligible to distribute your rewards. As an example use case, you can run a Drops announcement campaign and allow only influencers you’ve selected to reward Drops. To allowlist channels for access to the campaign:

1. Navigate to a Drop Campaign you have already created, and select the Access tab.
2. Use the search bar to select Twitch streamers you wish to allowlist access to the campaign. You can also type in Twitch User IDs (TUIDs). 
3. Save Changes when you have added these users. 

Best practices

The goal of a Drops campaign is to re-engage your audience and attract new players and viewers. Based on our experience with Drops, we offer these recommendations on running a successful Drops campaign:

1. A strong marketing effort for your Drops event goes a long way. Use your usual outreach channels (like blog posts and forums) to inform players about upcoming events. Leverage social media.
2. In your outreach, provide clear instructions for how players can link their Twitch and game accounts. Although Twitch notifies viewers about linking their accounts, having an FAQ and crystal clear list of steps makes it easier for your users.
3. Keep campaigns short and sweet. Rather than having one long campaign, use multiple short campaigns.
4. Offering a different set of Drops with each campaign is a big draw.
5. Offer Drops rewards that are unique to Twitch. This will draw more people to your campaign.
6. Give out different rewards for different periods of viewing. Start with something for watching 30-60 mins (or less). By offering a form of short-term gratification, you’ll get people hooked. Then offer even better rewards for viewers who watch longer; e.g., different (better) items for 2 hours of watching, 6 hours, and so on.
7. In your outreach, clearly communicate what viewers can earn at each milestone. In addition to your marketing communications, you can inform viewers about the items that can be earned by posting chat messages. 
8. Avoid stackable/transferable Drops rewards on global (across the entire game category) campaigns, as this encourages “farming” behavior. Avoid encouraging viewers to create multiple accounts and watch different channels from multiple browser windows. Another way to avoid farming is to provide Drops only on your official channel, using allowlist capability; thus enabling you to control the duration of a campaign on a daily basis.

Notify the viewers about earned Rewards

After you determine that the Twitch user has reached the viewing or broadcasting milestone, you provide the dropped item that is the user’s reward using your own entitlement system.

1. Create an application access token. This token is required for us to verify your request to generate a URL. If you try to use a user OAuth token for this request, it will fail.
2. Determine the list of users and entitle their accounts.

3. Request a URL by calling the Create Entitlement Grants Upload URL endpoint. When you call this endpoint, you must pass in a manifest_id (maximum length: 64 characters). We recommend using a GUID. Once you have the manifest_id and application access token, you’ll make a call with the manifest_id in a query string and the application access token in the Authorization header:

   curl -H 'Client-ID: <your client id>' \
   -H 'Authorization: Bearer <app access token>' \
   -X POST 'https://api.twitch.tv/helix/entitlements/upload?manifest_id=<manifestID>&type=bulk_drops_grant'
   

   You will get back a JSON object containing a URL like this:

   https://twitch-ds-vhs-drops-granted-uploads-us-west-2-prod.s3-us-west-2.amazonaws.com/<clientID>/<time>-<guid>-<manifestID>.json?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=<credential>%2Fus-west-2%2Fs3%2Faws4_request\u0026X-Amz-Date=<date>\u0026X-Amz-Expires=900\u0026X-Amz-Security-Token=<token>\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=<signature>
   

4. Edit the URL: replace \u0026 with & (ampersand). After the replacement, the URL above looks like this:

   https://twitch-ds-vhs-drops-granted-uploads-us-west-2-prod.s3-us-west-2.amazonaws.com/<clientID>/<time>-<guid>-<manifestID>.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=<date>&X-Amz-Expires=900&X-Amz-Security-Token=<token>&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
   

5. Create a JSON file (up to 100 MB) with the list of users to notify. The general structure of the JSON file is:

   {
      "campaign_id": "",
      "client_id": "",
      "game_watched": "",
      "broadcaster_id": "",
      "item_id": "",
      "reason": "",
      "users": ["1004321", "1004320", "1004319"]
   }
   

   For descriptions of the fields, see the Manifest file fields section.
   
   Note that one large JSON file gets processed much faster than multiple small files.

6. Send the JSON file to Twitch. We process it and notify users on the Twitch website. The notification will take the user to the Inventory page to see the Rewards they’ve been granted. If the viewer clicks the notification, your item name and image appear.
   To send the file, PUT it to the URL generated in the previous steps. This starts the processing and delivery of notifications to end users. For example:

 curl \
 --data-binary @manifest-file.json \
 -X PUT 'https://twitch-ds-vhs-drops-granted-uploads-us-west-2-prod.s3-us-west-2.amazonaws.com/<clientID>/<time>-<guid>-<manifestID>.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=<date>&X-Amz-Expires=900&X-Amz-Security-Token=<token>&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>'

If the upload is successful, you will get HTTP 200 OK back in response.

Manifest file fields