Drops Guide

This guide is written for game developers, to describe how to use Drops. Drops is a tool set that supports you in granting in-game rewards to your gaming communities natively within the Twitch viewing experience. Drops reports users’ game-viewing activity to you. You define the rewards and the reward logic. Drops allows you to tailor the viewing experience to the needs of players and the economy of your game.

Drops functionality is powered by:

  • Twitch Identity enables you to use a Twitch login on other applications.
  • The Twitch Viewer Heartbeat Service (VHS), a data-reporting service that pumps JSON data about a user’s viewing activity to an HTTPS endpoint hosted by you. You can use the incoming identities to select users for content entitlements and reward them as desired. For you to know which customers are watching on Twitch, your Web site or the game must integrate with Twitch Identity.

Drops brings viewers closer to games. By rewarding them for viewing, you create an ecosystem 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. Drops is the first in a series of new tools designed to help Twitch partners better engage and understand their Twitch communities.

This guide provides setup information. Also see the reference documentation for the associated endpoints:

Code samples are available on the Get Started page of the Twitch dev site.

Support

The Developer Success team is committed to helping you leverage the Twitch APIs and tools, for a more engaging experience for players, viewers, and broadcasters. If you run into any issues, visit our dedicated Drops forum.

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.

Sample JSON post:

{
	"broadcaster": "broadcaster-id-0000",
	"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
}

In the VHS JSON:

  • 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.
  • id is a random string generated for request differentiation.

Game Developer Integration Set-Up

Prerequisite: You must be able to access the Twitch developer site. If needed, request access to the site from https://dev.twitch.tv/request-access.

Setting up to integrate with the Drops subsystem is a multi-step process. Follow the steps below.

1. Authenticate with Twitch Identity

Follow the steps in the Twitch Authentication Guide. Authentication involves:

  • Registering with Twitch, to obtain a client ID and client secret. Retain your Client ID; you will need it below.
  • Getting an access token. When you authenticate on behalf of a user, you are granted an access token that uniquely identifies your client and the Twitch user to us. This includes specifying scopes, or the permissions you are allowed on behalf of the authorized Twitch user. To be able to hit the VHS endpoint, specify the viewing_activity_read scope when you request a token. Securely store this token for later use.
  • Sending the access token in your API request, to authenticate API requests.

2. Create an Endpoint to Receive VHS Data

You need to create an HTTPS endpoint to receive the VHS data. You will be able to 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.

3. Enable and Configure Drops

  1. Log into the Twitch developer site.
  2. Click Settings. The Settings screen for VHS Configuration appears.
  3. Enter the requested fields:
    • Client ID — From the authentication step above.
    • Endpoint — Your endpoint to receive the VHS heartbeats. Must be HTTPS.
    • Enabled — If checked, VHS will emit heartbeats. (Uncheck this if you need to do maintenance, for example.)
  4. Click Save.

4. Request VHS Data for the User

Once a user has linked his Twitch and game accounts, use the Create User Connection to Viewer Heartbeat Service (VHS) endpoint to create a VHS mapping and request VHS data.

5. Create a Drops Campaign

Drops campaigns let you notify viewers of your games when Drops are happening. During a campaign, unlinked viewers watching 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. Your account must be enabled to run a Drops Campaign. When you have implemented account linking and your endpoint is receiving VHS reports, please send an email to [email protected] to get approval to run Drops campaigns.
  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 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.
  4. Click Save.

6. 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.

Before starting, create an application access token. Follow the instructions in the App Access Tokens documentation. An application access 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. Then follow these steps:

  1. Determine the list of users and entitle their accounts.

  2. 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 similar to this:

    https://twitch-ds-vhs-drops-granted-uploads-us-west-2-prod.s3-us-west-2.amazonaws.com/<clientID>/<time>-<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>

  3. 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>-<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>

  4. Create a JSON file with the list of users to notify. This file can be up to 100 MB. 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.

  5. Send the JSON file to Twitch. We process it and notify users on the Twitch website.

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

7. Test Drops

Now you can 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 is 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 a short amount of time (5-10 minutes), you should start receiving heartbeats on your VHS endpoint.