Contents

Drops Guide

Introduction

Game developers: Drops are in-game rewards you can grant to your gaming communities, natively within the Twitch viewing experience. “Drops” refers to both the rewards and the tool set that supports you in granting them. Twitch reports users’ game-viewing activity to you, so you can define the rewards and reward logic for Drops. Drops allows you to tailor the viewing experience to the needs of players and the economy of your game.

Drops brings viewers closer to games. By rewarding viewers, you create a community that extends outside the game and enriches the experience when viewers return. We want to ensure that your players are rewarded for engaging in content around your game, whether they are playing or watching.

There are several visual indicators of Drops:

Drops functionality is powered by:

Step 1: Setup

If this is your first time using the Twitch developer site, register your company and game with Twitch.

Step 2: Authenticate with Twitch Identity

Follow the steps in the Twitch Apps & Authentication Guide to:

Step 3: 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 4: Enable and Configure Drops

  1. Log into the Twitch developer site, click Your Dashboard, then click Drops.
  2. Click Drops Settings, then enter the requested fields for VHS configuration:
    • Client ID — From the authentication step above.
    • Endpoint — Your HTTPS endpoint to receive the VHS heartbeats.
    • Enabled — If checked, VHS will emit heartbeats. (Uncheck this if you need to do maintenance.)
  3. Click Save.

Step 5: Request VHS Data for the User

Once users 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 those broadcasters’ viewers do not receive Drops.

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

What’s Next

Next: 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.

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:

Next: Test Drops

To set up your channel to test getting 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.

Next: Use 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 drops items (rewards) and creating a campaign (with specified items in it). Following these procedures, see our recommendations on Drops campaigns.

Creating & Editing Drops Campaigns (Rewards)

  1. Go to your developer dashboard: log into the developer site (https://dev.twitch.tv) and click Your Dashboard, or go to https://dev.twitch.tv/dashboard.
  2. Click Drops > Item Manager > + Create Drops Item.
  3. Enter the requested fields:
    • An Item Image (120x120 pixels) representing the Drop. Note that images are converted down to 80x80, which is loaded into the page in a 40x40 slot; this is done to support retina displays.
    • 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 Submit button is enabled. Click it to create the item, or click Cancel.

Creating & Editing Drops Campaigns

  1. Go to your developer dashboard: log into the developer site (https://dev.twitch.tv) and click Your Dashboard, or go to https://dev.twitch.tv/dashboard.
  2. Click Drops > + Create a Drops Campaign.
  3. Check Enable Campaign, to cause viewers to get notifications that Drops are available. If you are debugging a campaign with a problem, de-select this checkbox.
  4. Enter the requested fields:
    • Campaign Name
    • Start Date Time and End Date Time (in UTC) for your campaign.
    • (Optional) Games to which the campaign will apply.
    • Drops Connection URL, where unlinked viewers will be sent to create a connection.
    • Whitelisted Channels enabled for this Drop. Leaving this blank causes notifications on all channels streaming your game(s).
    • From the displayed Items, select up to 20 for this campaign.
  5. When all required fields have been entered, the Submit button is enabled. Click it to create the campaign with the selected items, or click Cancel.

Drops Campaign Recommendations

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 that having one never-ending campaign, use multiple short campaigns.
  4. Offering a different set of Drops with each campaign is a big draw.
  5. Offer Drops items that are unique to Twitch. This will draw more people to your campaign.
  6. Give out different items 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 items 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 using a chatbot. See the Chatbots & IRC documentation.
  8. Avoid stackable/transferable Drops items on global campaigns, as this encourages “farming” behavior; i.e., viewers will 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; this enables you to control the duration of a campaign on a daily basis.

Next: Notify the Viewer about Drops

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 '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 Manifest File Fields.

    Note that one large JSON file gets processed much faster than multiple small files (e.g., each containing only a few users).

  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 Drops they’ve been awarded. If the viewer clicks the notification, your item name and image appear.

    To send the file, PUT it to the URL generated above. 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.
client_idstringClient ID of the application for the Drops campaign.
game_watchedstringName of the game being watched for the Drops campaign.
broadcaster_idstringUnique ID of the broadcaster that was streaming the game.
item_idstring

(Optional) Unique ID of the Drops item. This determines the image and name the user sees in the notification. Twitch assigns this when a Drops item is created. You can see an item’s ID on your Twitch developer dashboard (https://dev.twitch.tv/dashboard): click Drops, then either:

  • For a list of all items, select the Item Manager tab.
  • For a list of items in a specific campaign, select the Campaign Manager tab, then click the campaign.

Note: We recommend you use this field. While it’s optional now, it’s expected to become required in the future.

reasonenumerationWhy the Drop is being awarded. This determines a portion of the notification the user sees. Valid value: watching.
usersstring []Array of IDs of viewers who have been entitled the Drop and will get a notification. (These are the same users you set in Step 5: Request VHS Data for the User.)