Contents

Drops Guide

This guide covers the Drops 2.0 version available to all organizations. This substantial update provides many benefits to companies wanting to engage the Twitch community. For Drops campaigns using the VHS heartbeat service, see the Legacy Drops guide.

Introduction

Twitch Drops enables you to grant in-game rewards to the Twitch community when streamers play your game or when they complete in-game missions, such as conquering a particularly difficult part of the game or by claiming victory during a battle royale game. Twitch Drops brings the Twitch community closer to your game, ultimately helping you acquire new players or re-engage your existing player base.

Our new version of Drops provides a significant improvement in the viewer experience by:

Twitch Drops provides many features for your company to get started with minimal setup, thanks to a built-in Rules Engine and Entitlements Service. The Drops Rules Engine tracks viewer watch activity, only distributing rewards based on the timeline you specify. Using the Enhanced Experiences (E2) API (Limited Access), you can set up missions for streamers to complete in-game to trigger a Drop to viewers watching the event live. For time-based Drops, you set the amount of time viewers need to watch the game on participating channels, and then Twitch will handle tracking their progress. Once a rule has been satisfied by the viewer, or the missions achieved by the streamer, viewers will be able to claim the Drops rewards and generate an entitlement. The Twitch Entitlements Service provides an easy-to-use interface to retrieve all viewers that earned rewards by participating in your campaigns.  

Important Terms

TermDefinitionExample
DropA collection of rewards distributed to viewers based on a drop rule during a specified time period.Limited Edition Soccer Balls
Drop RuleThe conditions viewers or streamers must meet in order to trigger a Drop to be claimed by Twitch viewers watching a live channel that participates in Twitch Drops.

Time-Based: Watch for 60 minutes

Event Based: “Total Domination” - The streamer must score at least 10 goals while the opposing team scores less than 1 goal.

RewardAn item that is granted by the company to viewers that are entitled to it. Typically, these are either consumables (e.g. coins), items (e.g. skins) or keys (e.g. beta-access keys).“Ultimate Ball”
Drop CampaignA collection of Drops that are distributed during a specified time period. Drops within a campaign must fall within the bounds of a campaign. Campaigns enable conditional drop setups to reward the most loyal viewers of your content on Twitch.“Super Soccer 2020 Launch”
EntitlementA unique identifier that tells developers which Twitch user earned a specific Drop (and its associated rewards) on Twitch.

  {

"id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",

"benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",

"timestamp": "2019-01-28T04:17:53.325Z",

"user_id": "25009227",

"game_id": "33214"

}

Campaign Status

Campaigns can be set to one of three states: 

Disabled - The campaign is not visible on Twitch. Any fields can be edited.

Test - The campaign is visible to Test viewers. Any fields can be edited.

Enabled - The campaign is visible to all viewers on Twitch and channels on the creator allow list (or, all creators if no list is specified). There are three states that are computed based on the dates of the campaign when a campaign is enabled:

  • Upcoming - The campaign is enabled but the start time has not passed.
  • Live - The campaign is enabled and the present time is between the start and end time.
  • Expired - The campaign is removed from Twitch because the campaign end time has elapsed.


disabled

test

enabled

upcoming

live

expired

Prerequisites and Setup

Once a developer within your company sets up Twitch Drops, campaigns can be created and managed by anyone within the company. 

Organization and Game Setup

In order to use Twitch Drops, you must have a Twitch Developer Organization and have claimed your Game that your Drop rewards are associated with, which will be distributed during live campaigns when creators stream your game on Twitch. For more information, see the Organizations documentation to get started.

Game ID

You will need the numerical Twitch Game ID for your game to use Drops. You can find your game ID by calling the following API endpoint: 

curl -H 'Client-ID: <your_client_id>' \
-H 'Authorization: Bearer <your access token>' \
-X GET 'https://api.twitch.tv/helix/games?name=<exact_game_name>'

Register Drops Clients

Drops uses the Twitch API to inform your game’s identity and fulfillment services which Twitch viewers have authorized you to grant rewards to their associated game accounts. You can use the same Twitch Application Client to authenticate Twitch users with your account services and to access the Entitlements API. To create a Twitch Client application, see the Authentication guide to get started. 

Note: Make sure your Client IDs are associated with your games on the Drops Settings page: 

Drops Settings button

The button can be found on the Drops Campaign page.

Account Linking 

In order to claim in-game rewards, Twitch viewers will need to link their Twitch and game accounts. They do so by providing your game service with a Twitch account <> game account mapping. When viewers link their accounts, we recommend that you save the following information:

When a viewer or streamer links their account for the first time, we recommend that you call the Get Drops Entitlements API to pull all of their entitlements for your game. 

While account linking can be achieved in-game, we also require that you host a webpage to let Twitch viewers link their accounts. You will need to add this URL to your reward configuration so that Twitch can redirect your viewers to the correct account linking page. 

You can read more about account linking with OAuth on the Twitch OAuth Guide

Entitlements API

The Entitlements endpoint provides Developers using Drops with a way to obtain a list of entitlements that have been granted to a user by their Drops. For detailed information on using the API, see the Twitch API Reference.

Definitions

Benefit

Field Type Description
benefit_id string Unique identifier for this benefit. This is the ID that will be returned in the entitlement APIs.
name string Name displayed to users on the site.
description string Description to be displayed to users on the site.
image_asset image Image to be displayed to the users on the site.
limit integer Number of times a user can be entitled to the benefit.

Entitlement

An entitlement is the link between a User and a Benefit.

Field  Type Description
id string Unique identifier of the entitlement.
benefit_id string Identifier of the benefit
timestamp string UTC timestamp in ISO format when this entitlement was granted on Twitch.
user_id string Twitch User ID of the user who was granted the entitlement.
game_id string Twitch Game ID of the game being played when the benefit was entitled.

Track Entitlement Fulfillments

We recommend that you track fulfillment for all rewards given out to game users. This will make sure that viewers receive their rewards. Here’s a simple sample data structure to track your entitlements. The entitlement ID is returned to you by the Get Drops Entitlements API. 

Entitlement ID Game User ID OAuth Token State
NDQ5MjY1Mzc2fH...4LTBhNThhOWZlYWMyYQ== GameAccount1 cfabdegwdoklmawdzdo98xt2fo512y CLAIMED
NDQ5MjY1Mzc2fH...4LTBhNThhOWZlYWMyYQ== GameAccount1 cfabdegwdoklmawdzdo98xt2fo512y FULFILLED
NDQ5MjY1Mzc2fH...4LTBhNThhOWZlYWMyYQ== GameAccount1 cfabdegwdoklmawdzdo98xt2fo512y EXPIRED

Campaign Marketing Page

You have the option of providing more information about your Twitch Drops Campaign by linking to a custom website, which will be available for the Twitch community to learn more about the event you are hosting. Typically this page includes more information about your event and how Twitch Drops will be a cornerstone of your marketing plan. For example, you may use Twitch Drops to drive viewers to watch your weekly developer diary stream on an upcoming game. The marketing page can tell viewers about the stream event, and can also inform them of the exclusive item you plan to give away.  

Rewards Manager

Before creating Drops Campaigns, you can use the Rewards Manager to set up the rewards you will associate to Drops that will be granted to Twitch viewers. Alternatively, you can add rewards while creating Drops within a campaign. When you create rewards via the Drops management interface, they will also be placed within the Rewards Manager.

Create a Reward

To create a reward, select the Rewards Manager within the Drops product via your Organization’s Console. Then, click the create new reward button to fill out the details of the item you will award to viewers who complete the Drops conditions (you’ll set these up later within a Drops Campaign). 

Field Name Details and Usage Example
Reward Image This image will display within the notification call out when a Drop campaign is enabled, the streamer dashboard, and the inventory card UI when a viewer earns the reward. It must be a 160x160 px JPG or PNG, less than 1 MB in size.  image of a shortsword
Reward Name The English name of the reward. In the future, we will allow localized names for rewards. Ultimate Ball
Game The game this reward is associated with. Games in this list must be owned by the organization and must have a Twitch Client mapped to it within Drops Settings. Super Soccer 2020
Reward Connection URL The URL viewers will go to link their Twitch account with your game’s identity service. Viewers expect that this identity link will provide the access needed to have the reward delivered to them after earning it on Twitch. https://supersoccer2020.com/link
iOS Based Reward If this reward is associated with an item that can be used within an iOS app or game, this field must be toggled ON.  OFF
Reward ID (optional) You can specify a unique ID for this reward, in case your game’s fulfillment service expects a certain identifier for the item granted. If you do not specify an ID, we will generate a GUID upon saving the reward on Twitch. 398dnb-9kdlsnm-dasdfk2-doandbo3-onbm21

After providing these details, saving the reward will make it available to any Drops added to a Drops campaign. 

Note: You cannot edit rewards that have been distributed in a previously active campaign. 

Create a Drops Campaign

To run a Drop on Twitch, you will first need to set up a Drops Campaign, which allows you to schedule several Drops in advance of the event you’ll host for the Twitch community. Prior to launch, campaign information will be displayed for creators, so they can ensure their streaming schedules align with your event. You can run up to five Drops during a campaign, which can last for as long as you want to run the event. 

Log on to the Twitch Developer Console and switch to your Organization’s console where you will create the campaign. Under the Drops product, select Create Drop Campaign. Add the following information that will be displayed for creators before, during and after your campaign:

Field Name Details and Usage Example
Campaign Image This image will be displayed for both viewers and creators before, during and after your campaign. It should visually summarize the event that your Drops will occur when creators stream your game on Twitch. It should be a 160x160px PNG or JPG and less than 1MB. image of a file box
Campaign Name This brief description gives streamers and viewers an overview of the campaign event. It can be no longer than 25 characters. “Super Soccer 2020 Launch”
Start Date & Time, End Date & Time The duration of the campaign event. All of the Drops set up within the campaign must be within the time frame specified at the campaign level here.  October 10th 2020 12:00PM to November 10th 2020 12:00PM
Game The game category creators must stream in order for Drops to be present on their channel. When a creator goes live during the campaign timeframe, viewers who visit the channel will have the ability to earn the Drops set up within the campaign. Super Soccer 2020
Default Locale (coming soon) If viewers do not provide a locale, this will default to English. In the future, you will be able to provide localized names, descriptions and other information.  English
Drops Connection URL The URL viewers must visit to link their Twitch account with your system which will fulfill the entitlements granted during the Drop Campaign.  https://supersoccer2020.com/link
Drops Detail URL (Optional) You can set up a marketing page to provide viewers and streamers more information about the campaign event, the rewards that they could earn, and the conditions required to earn the rewards. https://supersoccer2020.com/twitchdropslaunch
Description (Optional) This description is visible on the Drops page within the creator’s dashboard. It should cover all of the details of the campaign to entice creators to play your game during the campaign time period. Super Soccer 2020 is an arcade style soccer game that lets you play as the game’s legends at the world’s greatest stages… or at the public park. During October, we’ll be giving away exclusive balls that unlock certain capabilities within the game, exclusive to our fans on Twitch. See you on the field!

Once you create the campaign, you’ll be taken to the Campaign Details page where you can see a preview of how your campaign information and rewards will be presented to creators and viewers before, during and after the campaign. 

Next, you will set up Drops that will be distributed to viewers during the campaign. You can add up to five Drops, which can be distributed during continuous or concurrent time frames during the campaign. There are two types of Drops:

After adding the Drops to your campaign, you can test the campaign to ensure it is ready for your event, and then enable the campaign for creators when the campaign start time occurs.

Time-Based Drops

Time-Based Drops distribute rewards when viewers have watched a creator stream your game for a specified amount of time. Twitch monitors the amount of time viewers spend across all channels streaming your game, so all you have to do is fulfill the rewards they are entitled to. 

Add a time-based Drop to an existing campaign

Click on the Drops tab within a campaign and click the button to Create New Drop within the time-based card. Specify the name of the Drop and, optionally, provide alternative dates during which this specific Drop will be available during the campaign. You may wish to set one drop to occur during one week of a four week period, a second drop during week two, etc. 

Once you create the Drop, you’ll be taken to the Rules tab of the Drop to set the amount of time viewers must watch a creator streaming the game to earn the Drop Rewards. After selecting a time period, all you have to do is add the items to distribute when the condition has been met, and then you are ready for testing!

Time-based Drops support setting pre-requisite Drops that must be completed and claimed first before unlocking the ability to make progress toward another drop.  Please see Conditional Drops for more details.

Note: We recommend setting the watch time long enough for viewers to get a sense of the game, but not too much time that would demotivate them from earning your reward. Most campaigns set the watch time rules to be between 20 minutes and 6 hours. 

Add Rewards

Rewards are the items you will distribute to viewers after they have watched channels within the game category for the time specified in the Rules tab. You can add up to 20 rewards to a campaign, all of which will be dropped upon completion of the rule. You can add rewards either in-line during the Drop creation, or from the Reward Manager

Rewards can be anything from in-game items (e.g. a limited edition ball), consumable items (e.g. coins or points) or access to a game (e.g. beta access via a direct entitlement). Most Drops users distribute exclusive rewards you can only get on Twitch, distributing more rare items based on the difficulty of the rule specified. 

Test the Drop

We strongly encourage testing any Drop before you activate it as part of a Drops Campaign. To make sure your event is kept a surprise to the community, you can use two access lists to limit the number of accounts who can preview the Drop before it goes live to all viewers and creators. 

Specify Test Viewers and Creator Access

Click on the Access tab within a campaign and you will see two sections: Test Viewers and Creator Campaign Access. Test Viewers can participate in drop campaigns when the campaign status is in the test state. To specify test viewer(s), input their username(s) within the Test Accounts.

Creator Campaign Access allows you to specify creators whose communities can participate in your drop campaign. To specify creator(s), make sure Available for allow list channels is checked and the creator(s) username is entered amongst the Allow List Channels. The allow list is only valid when the campaign status is in test or active state.

Using one of the accounts that will watch your test stream, test out your account linking flow.

Stream on a linked streamer account 

Start streaming on Twitch using the streaming account you linked previously. 

Claim the drop with a test viewer and creator channel

Test that the user is able to claim an entitlement on Twitch. 

Verify the Entitlement was granted by Twitch

When a viewer claims a Drop, you can call the Entitlements API to get viewer entitlement data. 

Award a test Entitlement to the Twitch viewer

Make sure you are able to process entitlements and track fulfillment for your test users. 

Grant item in-game

Test that the user is able to claim an entitlement in-game. 

Event-Based Drops (Limited Access)

Event-Based Drops trigger when the streamer completes a set of conditions (i.e. missions) you specify within the rules engine. For example, you can reward viewers with a limited edition weapon when the streamer wins a match without taking any damage.

Note: This capability is powered by the Enhanced Experiences API, available in limited access to select Twitch Organizations. Please reach out to your Twitch contact to get started with Enhanced Experiences.

Add an event-based drop to an existing campaign

Within a Drops Campaign, select Drops and add a new Event-Based Drop. Once you create the Drop, you’ll be automatically navigated to the Rules tab. Here’s you’ll set up the event-based rule that must be satisfied to trigger the Drop to viewers on Twitch.

Set up an event-based rule

Event-Based rules require a Twitch Application Client to be allowlisted for access to E2. Select the E2 Client that the rules engine should expect a game state payload from to match against the rule specified within this form. The following table describes the remaining fields required to complete the rule setup:

Field NameDetails and UsageExample
Mission NameOn Twitch, the community knows the Drop occurs during an event when a notification appears that the streamer must complete a “mission” to earn the rewards for the event. 

The mission name is the short description for the mission to be completed by the streamer. This will be visible in their upcoming campaigns list, and also will be visible in the preview notification sent to viewers watching a live stream with the Campaign Enabled.
"Total Domination”
Mission DescriptionThe mission description describes the state that must be detected by E2 (and thus, the set of conditions that the creator must pass) to trigger the drop. This mission is shown to creators within the campaign details page on the creator dashboard. “The streamer must score at least 10 goals while the opposing team scores less than 1 goal.”
Drop Claim DurationThe amount of time the viewer has to claim the Drop after the mission has been completed by the creator streaming the game on Twitch. We recommend the default 2 minute allotment set within this form.2 minutes
Event Rule(s)

Each event rule is a pairing of a game state, a conditional operator, and value associated to the game state. You can add multiple event rules to a single Drop, which will likely make the mission harder to complete for the streamer

All rules must be satisfied to trigger the Drop. 

Rule 1: RedTeamScore is greater than or equal to 10

Rule 2: BlueTeamScore is less than or equal to 1

JSON Entry for Rule ValidationBased on the event rules specified, this field will auto populate a sample game-state JSON payload to send via the E2 API. Developers must submit this set of key-value pairs exactly to trigger the Drop, but they can exist alongside several other key-value pairs that describe the rest of the game state.
{“RedTeamScore” : 5,

“BlueTeamScore” : 4,

“GreenTeamScore” : 10

}

After filling out the rule, save changes and it will be available for testing when the campaign is in the test status. If you filled out this section on behalf of your development or platform team, be sure to send them the JSON entry generated after saving changes to ensure the drop triggers successfully when the creator completes the mission.

Add Rewards

As with time-based drops, you can add up to 20 rewards to be distributed once the event-based rule is satisfied by the creator. These rewards can be added in-line or via the reward manager. 

Test the Drop

As with time-based drops, the testing flow is similar: after setting the campaign into the test status, you will watch a testing channel with a test viewer account and await the rule condition to be met. You can test the Drop trigger by actually completing the condition in the game (thus sending the correct payload via the Enhanced Experiences API), or simulating the game state by sending the correct payload by posting to the Enhanced Experiences API directly. In either case, the game state event should trigger the drop claim notification; claiming the entitlement will update the Entitlements API endpoint with the associated viewer and drop earned.

Sending a test game state to the Enhanced Experiences API

{"connect":{"token":"xyz2j1sjzo8mhmbczowue123pqrst","session_id":"{4022E85A-X782-9613B-23E1-5A3773FFACDC}","game_id":"123456", "data":{{"RedTeamScore":5,"BlueTeamScore":4,"GreenTeamScore":10}}}

Enabling a Drops Campaign

Once you have added the Drops to the campaign and tested them within your company, you are ready to go live! Click Change Status to select the Enabled state. You will see a preview sheet of the campaign, which you can use as a last minute checklist for the details and drops you have set up for this campaign. 

Once you set the status to enabled, you will see one of three states:

State Visibility Campaign Edit Restrictions
Upcoming: The start time is in the future. Creators will be able to view campaign details in the creator dashboard. Campaign details can be changed.

The start date can be moved up to the present.
Live: The start time is in the past and the end time is in the future. Creators will be able to view the campaign details in the creator dashboard.

Viewers will see the game has Drops Enabled in the Twitch directory.

Channels streaming the game live will show Drops Enabled.

Viewers following streamers that go live with your title that has a campaign enabled will receive a notification encouraging them to tune in.
No changes can be made to any campaign or drop details.

The end date can only be moved to a future date.
Expired: The end time is in the past. The campaign will be hidden from all views. Any rewards earned by viewers will remain within their inventory, if they have earned them or claimed them already.  No changes can be made to any campaign or drop details.

Running a Successful Drops Campaign

A Drops campaign is most effective in conjunction with a marketing that drives interest to your campaign on Twitch. Throughout your game’s lifecycle, you can use Drops campaigns to attract new player interest in your title, or reward your most loyal fans. Here are a few tips to ensure your Drops campaign resonates with the Twitch community and excite your player base.

Create a Gaming Moment

Run a Drops campaign during a major moment for your game, such as its world premiere, beginning of open beta, or the release of a new trailer. With Twitch Drops, viewers can link their account to your identity system in advance of your game’s launch. You can seed viewer excitement with exclusive content that they will have available at Day 1 of launch.

Celebrate a Community Achievement

With Event-Based Drops, you can challenge creators to show off their skills and showcase the best of your game to the world. When a creator earns that hard fought victory, completes a devastating level or beats a major boss, you can trigger a Drop to generate a big moment around your game. 

Make Drops Rewarding

To make the biggest impact for your Drops Campaign, providing the rewards that excite your community is critical to achieving success.  Creating exclusive rewards such as beta access or a unique skin that can only be achieved through Drops will drive your audience to participate and attract new potential fans.

Be the First to Give News and Updates

Many developers use Twitch to showcase the latest updates in their game as part of a regular diary stream. You can set up Twitch Drops to be available during these streams, driving viewership to your show while showing off your latest release.

Conditional Drops Campaigns

Within a Campaign, you can chain together Drops of the same type to create a conditional Drops pattern, which you can use to award increasingly rare items as the community completes more difficult challenges.  This feature is also useful to encourage more interaction with a campaign by requiring more touch points and claim events for the user as they complete the different Drops in a campaign.

To set up a Conditional Drop Campaign, select a Drop within your campaign and, under Drop Details, toggle the Drop Condition and then select which Drop must be triggered before this Drop is available to viewers next.

Sample Campaign Structure

screen shot of the file structure

Using the Drop Dependency Tool

You can use the specific tool to visually specify the conditional pattern Drops will follow during the campaign. Select the Drops tab within the Drops Campaign and click the button to Modify Drop Dependency to get started. 

In the interface that pops up, you can click and drag drops (or use the arrow icons) to create a dependency pattern. A Drop Campaign can only have up to five drops, and a Drop Dependency pattern can only be made on three of the same Drop type. In other words, Event-Based Drops cannot be dependent on time-based Drops, and there can only be three tiers of Drop within a Dependency pattern. 

FAQ

Will Twitch Drops increase the rank of my game in the Twitch directory?

In conjunction with a strategic marketing campaign, Twitch Drops are effective in enticing creators to play your title and motivate viewers to check out your game on Twitch. We recommend working with our creators in advance of the campaign to make sure they can show off the best of your game during the Drops Campaign. We also recommend using other social channels to inform viewers about the Drop in advance.

Where can I get support for Drops?

We recommend reading the Twitch Developer Playbook to see how Drops fits in as part of a broader set of strategies to grow your game’s engagement on Twitch. 

To get additional support, see this page for all the resources available to you, including access to our Developer Forums and Developer Discord.

How do I remove an account link?

Since account linking is maintained by you, you will need to remove links between a Twitch account and a game account. We also recommend that you also revoke the OAuth access token

What type of rewards can I give out?

While we do not have specific recommendations on the types of rewards to give out, we do recommend that you avoid stackable/transferable Drops items, as this encourages farming behavior in which viewers create multiple accounts and watch different channels from multiple browser windows. 

How do I handle account de-linking by users?

It is important to think about how to handle users disconnecting their Twitch account from your game account. To check if a user has disconnected their account, you can check the validity of their OAuth token. 

Here are some recommendation on to handle account relinking by users:

How do I handle banned/suspended Accounts?

If an account is banned or suspended, the OAuth token is invalidated. Please check the validity of a user’s (streamer or viewer) OAuth token before granting in-game items.