Drops Guide

Introduction

Twitch Drops enables you as a game developer to grant in-game rewards to the Twitch community when streamers play your game. Twitch Drops brings the Twitch community closer to your game, ultimately helping you acquire new players or re-engage your existing player base.

Twitch tracks viewer watch activity for your games and distributes rewards based on the timeline you specify. When configuring your Drops campaign, you set the amount of time viewers need to watch one of your games on participating channels, and then Twitch will handle tracking their progress. Once a rule has been satisfied by the viewer, they 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 who earned rewards by participating in your campaigns so you can deliver the corresponding in-game items to your players.

Important Terms

Term	Definition	Example
Drops Campaign	A collection of Drops that are distributed during a specified time period. Drops within a campaign can only be earned between the campaign’s start and end dates.	“Super Soccer 2023 Launch”
Drop	A collection of rewards distributed to viewers based on a Drop rule during the campaign time period.	Limited Edition Soccer Balls
Drop Rule	The conditions viewers must meet on participating channels in order to earn a drop.	Watch for 60 minutes
Reward	An in-game item that is granted by a Drops campaign owner to viewers who 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”
Benefit	Benefit and Reward are interchangeable terms. Rewards are created in the Rewards Manager and are surfaced as Benefits in the API.	"398dnb-9kdlsnm-dasdfk2-doandbo3-onbm21" The above Benefit ID is the Reward ID of “Ultimate Ball”.
Entitlement	A record of a viewer earning a specific Drop (and the rewards it contains).	"fb78259e-fb81-4d1b-8333-34a06ffc24c0"
Campaign Status	Campaigns can be set to one of these six states: Disabled - The campaign is not visible on Twitch. Any fields within the campaign can be edited. Test - The campaign is visible to Test viewers. Any fields within the campaign can be edited. 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. Expired Manually - The campaign is removed from Twitch because a campaign owner canceled it before its scheduled end.

Prerequisites and Setup

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

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 will be associated with. For more information, see Organizations to get started.

Game ID

You will need the numerical Twitch game ID to use Drops. You can find your game ID by calling the Get Games 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>'

Create a Twitch Application for Drops

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 to authenticate Twitch users with your account services and to access the Entitlements API. To create a Twitch application, see the Get Started Guide for the Twitch API.

Whether you are creating a new Twitch application or using an existing one, you will need to identify which Twitch developer organization will be using the application for Drops from the application management page. Go to your Developer Applications listing page and click the “Manage” button for the application you will be using. On this application management page, use the “Organization” dropdown to select the appropriate organization.

Next, make sure the client ID of your Twitch application is associated with your games on the Drops Settings page. Look for the following button on the “Drops Campaigns” tab of the Developer Console for your organization.

Click the “Edit Details” button next to the game that will be using your Twitch application. Enter the Client ID of your Twitch application, which can be found on its application management page.

Account Linking

In order to claim in-game rewards, Twitch viewers will need to link their Twitch and game accounts.

In order to correctly link Twitch and game accounts:

1. Ask viewers to log into your account system
2. Ask viewers to authorize your Twitch application with their Twitch account
3. Store the Twitch account <> game account mapping

Note: Allowing a user to authenticate with Twitch before your account login may result in the user thinking the account is connected when it is not!

Specifically, we recommend that you store the following information:

• Game Account ID
• Twitch OAuth token
• Twitch Refresh Token
• Twitch User ID

While account linking can be achieved in-game, we recommend hosting a webpage to let Twitch viewers link their accounts. You can add this URL to your campaign configuration so that Twitch can redirect your viewers to the correct account linking page.

Refer to the Twitch OAuth guide for more information and options regarding how to authenticate Twitch users to achieve account linking.

You can read more about account linking with OAuth on the .

Entitlements Management

EventSub Subscription Type

EventSub is a third-party developer product that allows you to listen for real-time events. The drop.entitlement.grant subscription type sends a notification when an entitlement for a Drop is granted to a viewer. For detailed information regarding this EventSub topic, see Drop Entitlement Grant.

Get Drops Entitlements API endpoint

This endpoint retrieves entitlements that have been granted for a game, to a viewer, or both. For detailed information regarding this endpoint, see Get Drops Entitlements.

Update Drops Entitlements API endpoint

This endpoint updates the fulfillment status for a list of entitlements. For detailed information regarding this endpoint, see the Update Drops Entitlements documentation.

Tracking Entitlement Fulfillment Status

Generally, there are two approaches to tracking fulfillment status:

The following is the recommended integration flow:

1. Register an EventSub subscription for your organization. You may choose to create a subscription at the individual game or campaign level.

Below is a sample organization-level subscription condition for EventSub. It requires your organization id, which is the universal unique identifier found in the URL when viewing your organization on the Twitch developer console.

"condition":
  {
    "organization_id": "9001",
  }

Below is a sample game-level subscription condition for EventSub. A “category_id” is synonymous with the game id mentioned earlier provided by the Get Games API endpoint.

"condition":
  {
    "organization_id": "9001",
    "category_id": "33214"
  }

1. De-duplicate any entitlements sent to you over EventSub using the entitlement_id. It is possible for duplicate messages to be sent over EventSub in situations such as retries.
2. When a user launches their game launcher, query the Get Entitlements API for all claims for the user with fulfillment_status = CLAIMED.
3. Reconcile data that is received from EventSub as well as the Get Drops Entitlements API.
4. Grant in-game items to the user.
5. Update the fulfillment_status = FULFILLED on Twitch by using the Update Drops Entitlements API endpoint.

Definitions

Benefit

Entitlement

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.

Create a Reward

Before creating Drops Campaigns, you can use the Rewards Manager to set up the rewards you will associate with 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.

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 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.
Reward Name	The name of the reward.	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 2023
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://supersoccer2023.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 to ON. This will hide the Drops campaign on iOS devices. However, viewers’ progress on iOS will still be tracked and they would be able to claim the reward on other platforms.	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 This ID will be surfaced as benefit_id in the API.

After providing these details, saving the reward will make it available to any Drops added to a Drops 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 seven Drops during a campaign.

Log on to the Twitch Developer Console (using the dropdown menu at the top right) 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.
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 2023 Launch”
Start Date & Time, End Date & Time	The duration of the campaign event. All Drops set up within the campaign must be within the time frame specified at the campaign level here.	October 10th 2023 12:00PM (UTC) to November 10th 2023 12:00PM (UTC) * Campaigns have a 28-day maximum duration.
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 2023
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. *In cases where the account link connection cannot be done from a website, use this URL to link to detailed instructions on how to link the users Twitch and game accounts.	https://supersoccer2023.com/link
Drops Detail URL	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://supersoccer2023.com/twitchdropslaunch
Description	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 2023 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 seven Drops, which will be distributed over a concurrent time frame during the campaign. There is one type for Drops:

• Time-Based Drops: Viewers can earn the rewards within the Drop if they watch streams with Drops enabled during the Drop time period.

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.

Each participating streamer must have their Drops setting enabled as well as the associated Drops campaign setting enabled in order for it to be active on their channel.

Add a time-based Drop to an existing campaign

Click on the Drops tab within a campaign and click Create New Drop within the time-based card, then specify the name of the drop.

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.

If your campaign includes more than one Drop and you want viewers to earn each Drop at different lengths of time, simply configure the times accordingly. For example, if you have three drops within your campaign and want each to be earned 30 minutes after one another, set the first Drop for 30 minutes, the second Drop for 60 minutes, and the last Drop for 90 minutes. Viewers will progress on all drops at the same time but will only earn each Drops when completing the time-watch period specified.

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. Drops are limited to durations between a minimum of 15 minutes and a maximum of 4 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. You can add up to 3 rewards to a Drop, all of which will be rewarded 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 users of our Drops features 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.

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

2. Link a test viewer account

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

3. Stream on a Twitch streamer account

Start streaming on Twitch, ensuring (1) the category is set to your game, (2) within your creator dashboard Drops are enabled, and (3) Drops are enabled for your Drops campaign.

4. Claim the Drop with a test viewer and creator channel

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

5. Verify the Entitlement was granted by Twitch

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

6. Award a test Entitlement to the Twitch viewer

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

7. Grant item in-game

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

Enabling a Drops Campaign

Once you have added the Drops to the campaign and tested them within your organization, 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:

If you need to terminate the campaign while it is Live, you may change the status to Expired Manually.

Running a Successful Drops Campaign

A Drops campaign is most effective in conjunction with additional 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.

Be Thoughtful with your Campaign and Reward Names

Clear naming of your campaign and campaign rewards make for a better experience for creators and viewers. Consider using nomenclature your community is familiar with so there is a clear understanding of what the campaign is, and what rewards can be earned. As an example, a campaign name of “The Cool Game Winter Challenge Event” where you can earn “500 Super Gems” clearly illustrates what campaign is running and what rewards viewers can earn.

Limit the Number of Campaigns You Create

We have seen that having many concurrent global Drops campaigns running at the same time does not create a good user experience on Twitch, and in fact, causes user confusion and dilutes your message. We have also seen increased Customer Service activity for game developers when there are multiple campaigns running, with users reaching out to ask about individual rewards that they did not receive. If you do want to run multiple campaigns at the same time, we recommend having at most 2 campaigns on a channel at a time, with one global campaign and one channel specific campaign.

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.

Obligations

For more information regarding your obligations when running Drops campaigns, please see schedule 3 of the Developer Services Agreement.

FAQ

How long do I need to support a user claiming a Drop and linking their account after claiming for fulfillment?

In most circumstances, developers are required to fulfill viewer rewards that claim and link their accounts at least 14 days from the campaign ending. For certain time sensitive campaigns, such as a limited time beta, this requirement may be waived.

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.

How do I view campaign analytics for my Drop Campaigns?

A downloadable analytics CSV file will be made available in the near future.

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 the TwitchDev Discord server.

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. For more information on your obligations when running Drops campaigns, please see refer to the Twitch Developer Services Agreement.

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 recommendations to handle account relinking by users:

• Remove in-game entitlements for any game user accounts who unlink their account, in order to discourage them from farming for the same reward using different Twitch accounts.
• Any user that has linked their Twitch account to their game account and fulfilled in-game content cannot relink the same Twitch account to a second game account and fulfill the same in-game item.
• A user who has linked their Twitch account to their game account cannot fulfill additional in-game content by unlinking and linking another entitled Twitch account to the same game account.
• A user who has linked their Twitch account to their game account cannot transfer fulfilled goods to another game account (e.g. Steam marketplace, transfer content to another game account).

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.