Resources

Drops Guide

This guide is written for game developers, to describe how to use Drops, 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. 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 brings viewers closer to games. By rewarding them for viewing, 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. Drops is the first in a series of new tools designed to help Twitch partners better engage and understand their Twitch communities.

There are several visual indicators of Drops:

Game Directory Page — The Twitch game directory page indicates which games have an active Drops campaign open to all channels streaming the game. If the campaign includes a channel whitelist, there are no visual indicators on the game directory page.

Game Page — The page for a given game has an indicator if Drops are available to all channels broadcasting the game. If your Drops campaign is available only for whitelisted channels, this indicator is not displayed.

Channel Page — For Drops-enabled channels, the channel page has a visual indicator related to Drops. This 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; or the broadcaster has opted out of Drops.

Drops functionality is powered by:

Twitch Identity, which 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 your game on Twitch, your Web site or the game must integrate with Twitch Identity. That integration, and VHS, are described further, below.

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

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.

1. Authenticate with Twitch Identity

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.

4. Request VHS Data for the User

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

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.

Log into the developer site.

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.

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.

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:

Determine the list of users and entitle their accounts.

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:

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.

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.

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.

Link your channel, by going through the same OAuth flow that your viewers will go through.

Start streaming to your channel. After a short amount of time (5-10 minutes), you should start receiving heartbeats on your VHS endpoint.