Contents

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:

Drops functionality is powered by:

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:

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:

Also see the reference documentation for the associated endpoints:

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:

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

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 whitelist 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 whitelist 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 whitelist access to the campaign. You can also type in Twitch User IDs (TUIDs). 
  3. Save Changes when you have added these users. 
Important: When a campaign is enabled and the start time has occurred, the campaign is locked to users within this whitelist. If you wish to make changes, you must modify the whitelist or disable the campaign. 

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 whitelist 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

NameTypeDescription
campaign_idstringUnique ID of the Drops Campaign. You can find this in the top right corner when selecting an existing Campaign 
client_idstringClient ID of the application for the Drops campaign.
game_watchedstringName of the game being watched for the Drops campaign. This must exactly match the name in the reported VHS data, including case.
broadcaster_idstringUnique game account ID of the broadcaster that was streaming the game. 
item_idstring

(Optional) Unique ID of the Drops reward. This determines the image and name the viewer sees in the notification. Twitch assigns this when a Drops reward is created. You can see the reward’s ID on your Twitch developer console. Click Drops, then either:

  • For a list of all items, click the Reward Manager button.
  • For a list of rewards in a specific campaign, select the Drops Campaign tab, then click the Rewards tab.
Note: We recommend you use this field. While it’s optional now, it’s expected to become required in the future.
reasonenumerationWhy the reward is being awarded. This determines a portion of the notification the user sees. Valid value: watching.
usersstring []Array of game account IDs of viewers who have been entitled the reward and will get a notification.