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 200 or 204 status code in response. If one of these response codes is not returned, we re-POST the data at the next heartbeat interval.

Step 4: Enable and Configure Drops

  1. Log into the Twitch developer site.
  2. Click 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 queues data 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: Create a Drops Campaign

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.

  1. Log into the developer site.
  2. Click Start a Drops Campaign. The Drops Campaign screen appears.
  3. Enter the requested fields:
    • Start Date/Time — The date and time (PST) for your Drops campaign to start.
    • End Date/Time — The date and time (PST) for your Drops campaign to end.
    • Drops Connection URL — The URL where unlinked viewers will be sent to create a connection
    • Drop Item Name — The name of the item in the Drop.
    • Drop Item Image — An image (maximum size 120x120 pixels) representing the Drop. Images are converted down to 80x80, which is loaded into the page in a 40x40 slot. This is done to support retina displays.
    • Available on Games — The game(s) enabled for this Drop.
    • Whitelisted Channels — The channel(s) enabled for this Drop. Leaving this blank will cause notifications on all channels streaming your game(s).
  4. Click Save.

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": "",
       "reason": "",
       "users": ["1004321", "1004320", "1004319"]
    }
    

    For descriptions of the fields, see Manifest File Fields.

  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 on the notification, your campaign image shows up here.

    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

Name Type Description
campaign_id string Unique ID of the Drops campaign.
client_id string Client ID of the application for the Drops campaign.
game_watched string Name of the game being watched for the Drops campaign.
broadcaster_id string Unique ID of the broadcaster that was streaming the game.
reason enumeration Why the Drop is being awarded. This determines a portion of the notification the user sees. Valid value: watching.
users string [] 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.)