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:

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:

  1. Authenticate with Twitch Identity
  2. Create an Endpoint to Receive VHS Data
  3. Enable and Configure Drops
  4. Request VHS Data for the User
  5. Create a Drops Campaign
  6. Notify the Viewer about Drops
  7. Test Drops

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. Soon, Twitch will offer an endpoint that will allow you to notify your user about the reward on the Twitch Web site. Until then, user notification is your responsibility.

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.