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

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

An extension configuration comprises three types of configuration segments:

Segment TypeIs delivered to ...Can be set by ...
DeveloperViews of your extension on the associated channel.Developers
BroadcasterViews of your extension on the associated channel.Developers and broadcasters
GlobalEvery view of your extension, regardless of the channel.Developers

For extension examples that leverage the configuration service, see these repositories:

Setting Required Configuration with the Configuration Service (Optional)

Optionally, you can specify a required configuration when using the configuration service. In this case, you must specify versions of the broadcaster and developer configuration segments in two places:

These are compared when the channel is loaded. If they do not match, the extension will not load.

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

Testing Your Extension

After creating your extension and setting its capabilities, you are ready to begin testing and development. Extension development typically involves iterating locally over the extension and EBS, then transitioning your extension into a hosted state for additional testing and verification.

Local Test

To locally test your extension, you can use the Extensions Boilerplate or whatever you like, to act as a local Web server. Since some operations require HTTPS, you need to create and install a self-signed certificate on your system.

You can install your extension on your own channel, in the Extension Manager section of the Broadcaster Dashboard. While your extension is in Local Test or Hosted Test mode, only viewers on the testing whitelist can see it. Other viewers see your channel without any extensions.

Follow these steps:

  1. While logged in to Twitch, visit https://www.twitch.tv/dashboard.
  2. Click the Extensions tab, to go to the Extension Manager.
  3. Click the Invite Only tab (in the Extension Manager). This is where we provide tester and broadcaster whitelisted extensions.
  4. Install the extension into your account from the Extension Manager.
  5. If you are directed to configure the extension, see Required Configurations.
  6. Click Activate.
  7. Test your extension.

Hosted Test

When you are ready to begin testing your extension from the Twitch CDN:

  1. Gather your front-end assets into a valid ZIP format, retaining the directory structure. Ensure that:
    • Files are placed in the root of the ZIP directory.
    • You do not include non-extension files.
  2. On the Extensions Dashboard, go to the Versions tab for your extension.
  3. On the left panel, click Version Assets.
  4. Choose the appropriate ZIP file.
  5. Click Upload Assets.

This copies your assets to, and begins serving them from, the Twitch CDN. In this state, all your assets are hosted on the Twitch CDN, but the review process is not started. This gives you an opportunity to test your extension while hosted on the CDN.

If there is an issue with the upload (e.g., a file could not be accessed or your images are improperly sized), you are notified by email. To get these notifications, you must have verified the author email when creating the extension. Make sure you received a verification email when you created the extension on the dashboard and you clicked on the link in the email. If you have not done this, you will not get email notifications about any file-upload issues or when your extension is approved.

Pre-Release Disclosures

Until your extension is released, there are disclosures in the Extension Manager and on the channel page. The disclosures indicate that the extension is being tested and has not yet been evaluated or approved by Twitch.

Anyone on your testing or developer account sees these disclosures for your extension. On the channel page, the disclosure appears when your extension attempts to load. Users (anyone testing the extension) must accept a prompt, to proceed with the load. User choices for these prompts are not saved and persisted, so if the browser is refreshed, the disclosure appears again.  

The disclosures no longer appear once the extension version is released.