Contents

Building Extensions

Creating Your Extension Front End

As previously defined, extensions are front-end iframes. Now that you have created your extension and defined the settings of the first version of the extension, you are ready to create the assets that will live within the iframe.

Mobile Support

If your extension is intended for mobile devices, you can provide a second front end to be served on those devices. You can use an identical front end for mobile and web, if it is responsive enough to render and perform well on both platforms; otherwise, submit different front ends.

On the Twitch developer site, you are prompted to submit separate front ends for web and mobile. If you use the same viewer HTML for both web and mobile, we enable you to customize your behavior based on the native platform by providing your viewer with the query strings ?platform=mobile and ?platform=web.

Proper layout, rendering, performance, and interaction on mobile devices is very different from web, so if you are providing mobile support, test your extension thoroughly on the Twitch mobile app, to ensure a successful review.

Note: Due to requirements recently communicated to us by Apple, Extensions support on iOS devices (including the ability to test on iOS) is now restricted to Apple Developer Program members. If you develop a mobile extension for iOS, please set up an Apple developer account (if you do not already have one), then contact Twitch (developer_support@twitch.tv) to add iOS support.

Extension Helper Library

An extension’s iframe must import the Extension Helper JavaScript file, created and hosted by Twitch. It provides methods for dealing with authentication, receiving notifications of stream properties, and listening to PubSub events. Each HTML defined in the Asset Hosting section of your extension (Viewer, Config, Live Config) must load the Extension Helper. To do so, include this line:

<script src="https://extension-files.twitch.tv/helper/v1/twitch-ext.min.js"></script>

For details on the Extension Helper, including the callbacks and functions it provides, see the Extensions Reference.

Creating Your Extension Backend Service (EBS)

The EBS is your optional backend service that supports the extension. Your EBS can be written in whatever language you prefer. Depending on the nature of your extension, it generally should be capable of the operations described below.

Verifying the JWT

Your EBS needs to verify the communication it receives via any AJAX call from your extension. For example, it may need to enforce a policy that certain configuration tasks can be performed only by broadcasters. It also may want to ensure that a confirmed Twitch viewer, as opposed to an unidentified agent, is connecting to the EBS. As described above, the front-end iframe can obtain a signed JWT via the Extension Helper, using the onAuthorized() callback. The extension developer may then include this token as a header when making AJAX calls to the EBS.

JWT signing and validation libraries are available for many languages at https://jwt.io. They usually follow a calling interface similar to this:

verify(<jwt>, <secret>)

Where:

The JWTs used by Twitch Extensions expire, and verification of them fails after the expiration date. The Extension Helper automatically refreshes the token and then re-calls the onAuthorized() callback. Always use the latest JWT supplied by the Extension Helper.

For the full JWT schema and detailed notes on each field, see the “JWT Schema” section of the Extensions Reference.

Signing the JWT

In addition to verifying tokens signed by the Extension Helper, your EBS needs to be able to sign new JWTs for calls to various Extensions endpoints that use JWT as the authentication mechanism. For JWTs signed by your EBS, use the following format:

{
  "exp": 1502646259,
  "user_id": "27419011",
  "role": "external"
}

Where:

For more information about these fields, see the “JWT Schema” section of the Extensions Reference.

Sign the token using your JWT library. They usually follow a calling interface similar to this:

sign(<token>, <secret>)

Where:

Send your signed JWT in the request header, following this format:

Authorization: Bearer <signed JWT>

Broadcasting via PubSub

When the EBS wants to transmit realtime messages or state via PubSub, it will use the Send Extension PubSub Message endpoint. Using this endpoint, your EBS can broadcast to all viewers of a given channel or to specific user’ via a whisper.

Adhere to these limits for Twitch PubSub traffic:

These rules ensure the stability and scalability of our systems.

Required Configurations

If you specify configuration information in your EBS, you can optionally require that a broadcaster successfully configures your extension before activation is allowed. This can be useful if, for example, an active extension would show a confusing error message to all viewers if misconfigured. You enforce required broadcaster configuration with a string in the Required Configurations field. The contents of this string can be whatever you want. By using a string you provide within this field, you can easily require different configurations from version to version, so that if a new version requires reconfiguration, the broadcaster will need to complete configuration before activating the new version.

Once your EBS determines that the extension is correctly configured on a channel, call the Set Extension Required Configuration endpoint.

Configuration Service

The configuration service enables you to store persistent per-channel and per-extension data and have it provided to your front end on extension startup. This is a common need for most extensions. With the configuration service, you can quickly support scenarios like:

More importantly, with the configuration service, you do not need to expose your EBS to the extension front end on initial load, eliminating the need for your EBS to scale to support that scenario. In some cases, you can build an extension without an EBS, just by using the configuration service. (You can still build this functionality in your EBS, if you choose.)

Note: The configuration service is not a persistent data store, and should not be used as such.

If you use the configuration service, after choosing to use Twitch hosted configuration, data that is set via the set helper function (see Helper: Configuration) will be provided to the extension during bootstrap.

An extension configuration is comprised of segments, which consist of three values: the type, the version (used in required configuration), and the configuration value. These segments have varying properties:

Segment TypeIs delivered to EBS and ...JWT Role
developerviews of your extension on the associated channel.external
broadcasterviews of your extension on the associated channel.external and broadcaster
globalevery view of your extension, regardless of the channel.broadcaster

For extension examples that leverage the configuration service see the new Twitch API Reference. Also, see these repositories:

Setting Required Configuration with the Configuration Service (Optional)

If you choose, you can also specify a required configuration when using the configuration service. This compares the value given in the Extensions Manager to the version value for the extension in the given segment. If this value does not match, the extension won’t be able to activate. You can use this service to ensure broadcasters are configuring your extension correctly.

In this case, you must specify versions of the broadcaster and developer configuration segments in two places:

These versions are compared when the channel is loaded. If they do not match, the extension will not load for both broadcasters and viewers until the broadcaster reconfigures it.

Managing Extension Secrets

Each extension maintains a shared secret that is used to sign and verify JSON Web Tokens (JWT) that provide the identity of users. Use this authentication method when making Extensions API calls from your EBS (for endpoints that support it).

Twitch extension technology relies on a secret shared between the Twitch API and the EBS, to validate JWTs. This secret has an extremely long life (100 years); however, we strongly recommend that extension developers rotate the shared secret often, to better ensure its security.

JWT Roles

Both the EBS and Twitch create JWTs.

The EBS should create and sign JWTs with the external role to perform API actions. Twitch creates JWTs with other roles, so the EBS can perform user authentication. Both use cases (the external role and other roles) use the same secret. (For a discussion of roles, see the “JWT Schema” section of the Extensions Reference.)

Creating Your First Secret

  1. Go to the Settings page of your extension in the Extensions console.
  2. On the left panel, click Secret Keys.
  3. Click Create New Secret to generate a new secret key. You will see the following:
    • Key — The secret, base64 encoded.
    • Active — UTC timestamp when the secret becomes active. This allows the secret to propagate through both Twitch servers and the EBS, before you use it.
    • Expires — Timestamp when the secret expires. This is the latest time to use this secret to verify a JWT; the JWT should be discarded after this time.

Rotating Secrets

You must rotate your secrets before they expire. To do so, create a new secret on the extension’s Settings page under Secret Keys. The table will update, showing when the previous key will expire and the new key will be active.

Because of the activation delay, you can have multiple secrets active for some (configurable) period of time. For signing, use the active secret with the latest expiration time.

Optionally, you can create new secrets with the Create Extension Secret endpoint. For a higher level of security, you can programmatically rotate secrets on a scheduled basis.

Revoking All Secrets

At any time, if your secrets are compromised, the Revoke All Secrets option can be used on the extension’s Settings page under Secret Keys. View this as a kill switch: it immediately deletes all secrets associated with a specified extension.

Optionally, you can revoke all secrets through the Revoke Extension Secrets endpoint.