Contents

Enhanced Experiences (E2) Authorization SDK Guide

Introduction

The Twitch Authorization SDK is a library that provides access to Twitch Authentication through an API targeted at applications used by Twitch broadcasters.

Note: In this document “authorization” refers to both authentication and authorization.

The audience for this document is game developers. Game developers use the Authorization SDK to authenticate with Twitch Identity. After authenticating, game developers can use Twitch Prime, link their identity system with Twitch (Account Linking), or another game integration on Twitch (e.g., Drops or Insights & Analytics) as well as the Twitch API and other Twitch services.

There are two versions of the Authorization SDK:

This document describes both versions. Most of the classes and methods are similar between the two versions, so familiarity with one will help you learn the other. There are several library files, both static and dynamic, for these platforms in both debug and release builds.

Authorization

To configure your application for use with Twitch Authorization, refer to the Twitch Authentication Guide.

The Authorization SDK has four forms of authorization: three based on directly on OAuth and a third that also provides an OAuth token:

Since the StartAuth methods use the platform’s networking stack, they return platform-specific asynchronous result objects; they take some time to complete.

Both the ServerAuth and ClientAuth classes inherit the BrowserAuth class since the OAuth authorization mechanisms they use involve a Web browser. Each platform has its unique browser behavior. The BrowserAuth class has no useful interface; it is for internal use.

Windows

The StartAuth methods of both BrowserAuth-derived classes open users’ default Web browsers. Since it is in a process separate from that of the application, it is up to users to complete the sign-in process. If users instead choose to close the window, the application must provide some mechanism for the user to cancel the current process. One option is having a Cancel button in the application’s UI while users goes through the OAuth process in the browser. If users press the button to signal they want to cancel the operation, the application invokes the Cancel method.

PlayStation 4

The StartAuth methods of both BrowserAuth-derived classes open the PlayStation 4 Web browser. The browser operates modally so the application knows when it closes. There is no need for a Cancel button.

Nintendo Switch

The Nintendo Switch has only DeviceAuth since it has no browser.

Android and iOS

The StartAuth methods of both BrowserAuth-derived classes open a platform-specific Web view. It is up to application developers to allow room around the Web view for a Cancel button.

C++

SDK Types

All types in the Authorization SDK are in the Twitch namespace.

Aliases

Several C++ built-in types and standard library classes have aliases (typedefs) since their types can vary based on the character type (i.e., char or wchar_t).

On Windows-based platforms (i.e., Windows and Xbox One), the Authorization SDK assumes the use of Unicode. In this case, the string types and types dependent on those strings (e.g., std::wstringstream) use wide (16-bit) characters.

On other platforms (e.g., PS4), those types use single-byte (8-bit) characters.

The common header file, BaseSDK.h, contains the aliases, notably:

Threading

Several parts of the Authorization SDK run asynchronously due to long-running network activities. To ensure clients are in control of the execution of their applications, the Authorization SDK uses C++ std::future objects to provide asynchronous execution. This enables three different threading modes, described below.

Client Multi-Threading

In this mode, the client has multiple active threads and controls all threads.

Methods returning std::future objects create objects with std::async, with a launch policy of std::launch::deferred. This means the part of the invoked method that runs asynchronously will not run until the client invokes either the get or wait method of the returned std::future object. To prevent blocking the main thread, the client will invoke the get or wait method on a separate thread. This provides the greatest control over the timing of the deferred execution, since the client thread chooses when to invoke the get or wait method.

If an exception occurs during the deferred invocation, the get method throws that exception.

The client is responsible for synchronizing access to state shared among any threads it creates.

SDK Multi-Threading

In this mode, the client uses only one thread directly but is aware of and accounts for additional threads.

The client wraps methods returning std::future objects with Callback objects, providing call-back functions to those objects. Such objects invoke the call-back functions passed to them on a different thread than the one which invoked the method which created the Callback object, since the Callback objects run the asynchronous part of such methods on a thread launched with std::async with a launch policy of std::launch::async.

The client is responsible for synchronizing access to state shared among the call-back thread, the invoking thread, and any other threads the client creates.

The lifetime of a Callback object must encompass the entire activity, so do not destroy a Callback object until its associated call-back function has run.

Single Threading

In this mode, the client has one thread and performs no state synchronization.

The client wraps methods returning std::future objects with Pollable objects. These objects create internal threads. Such threads are not exposed to the client and do not access client state, so no synchronization is required.

Clients running a “game loop”, such as an update-render loop, can check the IsReady property of the Pollable object to determine if the result of the operation is available. When it is true, the client can use the other properties of the Pollable object to get the value (if the method was successful) or the exception (if it was not). All such methods are guaranteed to return quickly, making them suitable for use in a game loop.

The lifetime of a Pollable object must encompass the entire activity. In other words, do not destroy a Pollable object until its IsReady property returns true.

Methods returning void do not create internal threads. If they have long-running components, the object will provide properties to check the status (e.g., IsReady) and get the result (e.g., Value), much like the Pollable objects.

C#

SDK Types

All types in the Authorization SDK are in the Twitch namespace.

Threading

Unity is multi-threaded internally but its public interface is single-threaded. All UI elements are accessible only on the main thread. Unity uses coroutines to achieve asynchronicity.

The Authorization SDK has a utility class, Coroutine<T>, which implements System.Collections.IEnumerator and is suitable for use in Unity coroutines. All asynchronous methods in the Authorization SDK return an object of this type. The template class T is the type of the desired final result of such a method.

When the coroutine is complete, the Coroutine<T> instance makes the result available in its Value property. If a method is asynchronous but has no useful result, T is object and the Value property is undefined (usually null). Before the coroutine is complete, all public properties are undefined.

If an asynchronous method fails, accessing the Value property will throw an exception. If you do not want to have to handle such exceptions, check the Exception property first. If it is null, it is safe to access the Value property.

Docs Status Support Showcase Blog