Contents

Enhanced Experiences (E2) Guide

Introduction

Twitch invites you to build a pilot integration with our Enhanced Experiences API, offering new ways for viewers and streamers to discover and engage with your game. Since the earliest days of Twitch, game developers have created innovative experiences for live streaming using our developer products, such as Twitch Drops and Extensions. The applications that have driven the most awareness, engagement, and player base for games are those that:

  1. Make your game’s experience on Twitch feel like a natural extension to your game’s content and brand.
  2. Take advantage of the native, fast pace of live-streaming content by augmenting it with real-time information— enabling streamers to focus on game play and the show and the game companies to focus on the rest of the details.

The Twitch Enhanced Experiences (E2) API offers a turnkey method to achieve (1) and (2). After setting up the integration, your game’s presence on Twitch is expanded to make it easy for viewers to find, watch and engage with your game and its content.

Your data will enable the following experiences event-based Drops at launch, however we will continue to monitor and look to see how we can continue building in the future. 

Getting Started

To get started, you’ll need to have a Twitch Client ID and  game ID allowlisted. To be allowlisted, please fill out this form to request your client and game are allowlisted. A Twitch representative will reach out once this has been done. 

Once you’ve been allowlisted, you’ll want to download the E2 SDK here: https://gsdk.twitchcdn.net/TwitchSDK.zip and see the guides: 

The SDK is the only official way to send data to E2. 

Architecture Overview

Enhanced Experiences architecture diagram

To integrate with Twitch’s Enhanced Experiences (E2) product, we provide an SDK that lets you connect and send game state packets from your game server (or client). When a streamer is live, our service will be available to ingest and process game data from their session. Twitch will then leverage this data to amplify the viewing and streaming experience of your game, by powering Drops and interactive Extensions and providing targeted recommendations to Twitch viewers.

You control your data: Twitch will utilize the data from your game to provide the best experience of your game on Twitch. As always, you control what you provide to Twitch.

Data Ingest

Twitch ingests data through the SDK . Authentication is performed using a Twitch OAuth application token for server-side data delivery, or with a Twitch single user OAuth token when pushing data from the client side.

When multiple broadcasters share the same data, you may utilize the broadcaster_ids field to send one message for all broadcasters. If you want to send data that is unique for each broadcaster, you must open a connection for each broadcaster for that unique data. On connection or reconnection of the game server or game client to Twitch, all required data should be sent. After those events, only changed data should be sent in each packet. This changed data should be calculated following Delta State generation on the data source side.

Going Live

Both client- and server-side implementations should only transmit state for active streamers to minimize bandwidth and performance bottlenecks. Streamers need to link their account with an OAuth connection related to the specific game, and this account link should be leveraged to subscribe on the data source to a stream change webhook for “Go Live” events which fire upon the beginning of a stream. The Twitch “Get Streams” API is also available for checking if a user is live. An OAuth connection is necessary to translate from a game specific user ID to a Twitch User ID.

Authentication

Accepted token types

Both user token and app token are accepted for E2. If it is client side data, user token is the only option. If it is server side data, it is still welcome to send us user token if possible, but app access token will be accepted too with validations that the broadcasters you are trying to send data to have authorized your app.

Allowlist needed

You will need to be allowlisted for the client ID & game ID combination with us to begin publishing data.

Specifying Broadcaster ID

Broadcaster ID is only needed when using app access token, your message will be rejected if broadcaster id is passed in for user token, because you could potentially be requesting to send data on another user’s behalf.

Guidelines

General Best Practices

Authoritative data

Authoritative data must be sent from the server side using app token. If data is not authoritative, it may be faked by users to trigger desirable events, which may have monetary costs especially when tied to valuable in-game items available through Drops. It is ideal to send data from the server because of this. 

It is recommended to always use app token from server side instead of user token from client/server for reliability. E2 will distinguish those two types of tokens and decide its credibility.

Shared data

If several broadcasters are sharing the same game data, it is recommended that game devs combine them in broadcaster_ids field to save connections needed for data transmission.

Consider a scenario where a game has 100 concurrent players, with 10 of them streaming to Twitch, and your E2 implementation is sending data from the server side. You could save resources by combining those 10 streamers’ data into one payload through one connection for a game. Please note that, if there is privacy issue for each streamer data, this approach should not be used.

Data rate should not exceed 1 message/sec and the connection cannot be idle for more than 3 minutes not sending any game related data.

Dealing with Server Failures

Upon unexpected E2 failure situations, Twitch will send a reconnect message specifying the time in milliseconds. Your application should attempt to reconnect to E2 after this time.

Issue disconnection wisely

When a game session is completed, disconnect should be initiated by the game server/client to avoid further resource consumption.

Don’ts for authentication token

Please do not pass “Bearer” or “OAuth” with a token to the token field like Twitch REST endpoints. It will not be accepted in our websocket connection.

Make sure the token is not expired when passing to E2. An expired token will be rejected.

Data suitable to E2

Twitch will leverage metadata you send to the Enhanced Experiences system(via the JSON object sent in the data field) to power a wide variety of experiences on Twitch that will benefit discovery and engagement with your game.

Note: Begin by sending a few data fields at intervals your systems can handle – Twitch can still provide benefit to your game even with low resolution data!

Scenarios for failure

E2 will either error or disconnect connections based on the following rules to ensure a better usage of resources.

Rules Description
Rate Limiting A connection will be terminated if it sends over 1 message (all types included, connect, delta, refresh, flush…) per sec. We have a one minute bucket using a fixed window algorithm now. (Please see the “Rate-Limiting” section below)
Idle Checker A connection will be terminated if it is idle for over a customized time (max is 195 seconds auto close when not sending any data through active connection. Please see the “Idle Checker” section below).
Message Size Connect message and refresh message have a size limit for 100KB and delta for 20KB. Any messages exceeding the accepted size will be rejected and make E2 to send back errors.

Rate-Limiting

E2 is rate-limiting its client to avoid abuse of messages through one connection.

Key Facts

Best Practices

Idle Checker

E2 implements a deadline for the next message which is 195 seconds (3 minutes + 15 seconds buffer time), which means it is recommended that any connection could not be idle for more than 3 minutes.

Best Practices

Message Size Limit

Full size payload (connect and refresh) will have a limitation for 100KB and delta message will have limitation for 20KB.

Key Facts

Best Practices