Extensions Reference

Reviews for organizations and chatbot verification continue to be temporarily paused while we revise our processes. Reviews for Extensions and game ownership have resumed. Thank you for your patience and understanding.

As of July 9th 2024, there is no longer a requirement to have an Apple Developer account, or fill out the "iOS Allowlist Request" form, to allow an Extension to work on the iOS version of the Twitch app. All mobile Extensions, existing and new, are available on iOS and Android without additional requirements in the submission process.

This reference covers the JavaScript helper, client query parameters, and the JWT schema. For Twitch API endpoints related to Extensions, refer to the Twitch API reference.

JavaScript Helper

Helper: Extensions

The Extensions JavaScript helper uses these strings:

• version — This encodes the Helper version in 1.1.1 (semantic versioning) format.
• environment — This encodes the environment. For external users, this is always production.

onAuthorized

window.Twitch.ext.onAuthorized: function(authCallback: Function)

This callback is fired each time the JWT is refreshed.

authCallback is a function with one argument, an object with these properties:

For example:

window.Twitch.ext.onAuthorized(function(auth) {
  console.log('The JWT that will be passed to the EBS is', auth.token);
  console.log('The channel ID is', auth.channelId);
});

Usually, the JWT obtained from this call is passed as a header during AJAX calls to the EBS. For example:

window.Twitch.ext.onAuthorized(function(auth) {
  fetch('/<some backend path>', {
      method: 'GET',
      headers:{
        'x-extension-jwt': auth.token,
      },
  })
    .then(...);
});

onContext

window.Twitch.ext.onContext: function(contextCallback: Function)

This callback is fired when the context of an extension is fired.

contextCallback is a function with two arguments, a context object and an array of strings naming the context properties that were changed. The context object has these properties:

onError

window.Twitch.ext.onError: function(errorCallback: Function)

This callback is fired if any errors are generated by the extension helper.

errorCallback is a function with one argument, the error value, when any errors occur within the helper.

onHighlightChanged

window.Twitch.ext.onHighlightChanged: void function(callback: Function)

This function allows an extension to adjust its visibility when the viewer highlights the extension by hovering over the extension’s menu icon or open menu, in the video player. The function applies only to video-overlay and component Extensions.

onPositionChanged

window.Twitch.ext.onPositionChanged: void function(callback: Function)

This function registers a callback that gets called whenever an extension changes position in the player. This applies only to video-component extensions. This also is triggered as the extension loads.

onVisibilityChanged

window.Twitch.ext.onVisibilityChanged: void function(callback: Function)

This function registers a callback that gets called whenever an extension is hidden/re-shown, either due to the viewer’s action or due to extensions hiding due to the video player changing to a state where extensions are not shown (such as when the video pauses or an ad is running). When an extension is not visible, it does not receive onContext updates and must perform only minimal work in the background.

send

window.Twitch.ext.send: function(target: String, contentType: String, message: Object) window.Twitch.ext.send: function(target: String, contentType: String, message: String)

This function can be called by the front end to send directly to PubSub. It uses the Twitch-provided JWT for broadcasters, to allow broadcasters to send a broadcast (channel) or whisper message. Broadcasters cannot send to global.

listen

window.Twitch.ext.listen: void function(target: String, callback: Function)

This function binds the callback to listen to the target topic.

Whispers are a set of optional PubSub channels that extensions can use. Each copy of an extension can register for "whisper-<userId>" where userId comes from the onAuthorized message. Attempts to listen to another userId will be blocked. Once the extension is listening, the EBS or broadcaster can send an individualized message to the channel.

unlisten

window.Twitch.ext.unlisten: void function(target: String, callback: Function)

This function unbinds the listen callback from the target.

Helper: Actions

followChannel

window.Twitch.ext.actions.followChannel: void function(channelName: String)

This function prompts users to follow the specified channel, with a dialog controlled by Twitch. When users confirm (through the dialog) that they want to follow the channel, the callback registered with Twitch.ext.actions.onFollow is invoked.

minimize

window.Twitch.ext.actions.minimize: function()

This function causes your video-component or video-overlay extension to be minimized.

onFollow

window.Twitch.ext.actions.onFollow: void function(callback: Function)

This function registers a callback that is invoked whenever a user completes an interaction prompted by the followChannel action.

requestIdShare

window.Twitch.ext.actions.requestIdShare: function()

This function opens a prompt for users to share their identity. After a successful identity link, the Twitch.ext.onAuthorized callback is invoked with the user’s ID. This function has no effect if:

• Your extension does not have identity linking enabled.
• It is called when the extension is installed on the user’s own channel.

Helper: Configuration

broadcaster

window.Twitch.ext.configuration.broadcaster: {version: string, content: string}|undefined

This property returns the record for the broadcaster segment if one is found; otherwise, undefined.

developer

window.Twitch.ext.configuration.developer: {version: string, content: string}|undefined

This property returns the record for the developer segment if one is found; otherwise, undefined.

global

window.Twitch.ext.configuration.global: {version: string, content: string}|undefined

This property returns the record for the global segment if one is found; otherwise, undefined.

onChanged

window.Twitch.ext.configuration.onChanged: void function (callback: Function)

This function registers a callback that is called whenever an extension configuration is received. The callback function takes no input and returns nothing. After this is called for the first time, the records for the global, developer and broadcaster segments will be set if the data is available.

set

window.Twitch.ext.configuration.set: void function (segment: String, version: String, content: String)

This function can be called by the front end to set an extension configuration. It uses the Twitch-provided JWT for broadcasters, to allow broadcasters to set a broadcaster configuration segment.

Helper: Feature Flags

isBitsEnabled

window.Twitch.ext.features.isBitsEnabled: Boolean

If this flag is true, Bits-in-Extensions features will work in your extension on the current channel.

If this flag is false, disable or hide the Bits in Extensions features in your extension.

This flag will be false if:

• You did not enable Bits support in the Monetization tab in the Extensions manager.
• The broadcaster is not eligible to receive Bits.
• The broadcaster disabled Bits in Extensions features for your extension.

isChatEnabled

window.Twitch.ext.features.isChatEnabled: boolean

If this flag is true, you can send a chat message to the current channel using Send Extension Chat Message (subject to the authentication requirements documented for that endpoint). This flag may be false if:

• You did not enable the “Chat Capabilities” option for your extension on the Twitch developer site.
• The broadcaster disabled chat for your extension.

isSubscriptionStatusAvailable

window.Twitch.ext.features.isSubscriptionStatusAvailable: boolean

If this flag is true, your extension has the ability to get the subscription status of identity-linked viewers from both the helper in the window.Twitch.ext.viewer.subscriptionStatus object and via the Twitch API.

This flag may be false if:

• You did not enable the “Subscription Status” option for your extension on the Twitch developer site.
• The broadcaster did not grant your extension the permission to view their viewer’s subscriber status when they activated the extension, or they revoked that permission from the Manage Permissions page.

onChanged [features]

twitch.ext.features.onChanged: void function(callback: Function(changes: []string))

This function enables you to receive real-time updates to changes of the features object. If this callback is invoked, you should re-check the window.Twitch.ext.features object for a change to any feature flag your extension cares about. The callback is called with an array of feature flags which were updated.

callback is a function with one argument:

Helper: Bits

Some functions use the Product object. Here is an example (fields are described under getProducts):

{
    "sku": "carrot",
    "displayName": "Carrot",
    "cost": {
        "amount": "500",
        "type": "bits"
    }
    "inDevelopment": true
}

getProducts()

window.Twitch.ext.bits.getProducts: {Promise: Product[]}

This function returns a promise which resolves to an array of products available for Bits, for the extension, if the context supports Bits in Extensions actions. Otherwise, the promise rejects with an error; this can occur, for instance, if the extension is running in the legacy developer rig or an older version of the mobile app (earlier than V6.4), which does not support Bits in Extensions actions.

Products are returned only if the extension is configured for Bits (see the Extensions Monetization Guide). The products that are returned depend on the state of both the extension version (whether it is released) and the product (whether the kit is in development):

Products have the following fields:

onTransactionCancelled

twitch.ext.bits.onTransactionCancelled: void function(callback:Function)

This function takes a callback that is fired whenever a transaction is cancelled. A transaction can be cancelled in several ways:

• The user clicks the Cancel button.
• The user closes the confirmation dialog by clicking outside it.
• The useBits function fails and the user dismisses the error dialog that is displayed.

onTransactionComplete

window.Twitch.ext.bits.onTransactionComplete: void function(callback: TransactionObject)

This function registers a callback that is fired whenever a Bits in Extensions transaction is completed. The callback receives a TransactionObject with these fields:

setUseLoopBack

window.Twitch.ext.bits.setUseLoopback: boolean

This function sets the state of the extension helper, so it does not call live services for usage of Bits. Instead, it does a local loopback to the completion handler, after a fixed delay to simulate user approval and process latency.

showBitsBalance

window.Twitch.ext.bits.showBitsBalance: void

Call this function when the viewer hovers over a product in your extension UI, to cause the Twitch UI to display a dialog showing the viewer’s Bits balance. The dialog displays for 1.5 seconds, unless your extension calls showBitsBalance again, in which case the 1.5-second timer resets.

This is a “fire-and-forget” function: the extension developer does not need to tell Twitch when the viewer stops hovering over the product.

On mobile, this function is ignored.

useBits

window.Twitch.ext.bits.useBits: void function(sku: String)

This function redeems a product with the specified SKU for the number of Bits specified in the catalog entry of that product. For more information, see Exchanging Bits for a Product.

Helper: Viewer

The Twitch.ext.viewer object is a collection of info about the twitch viewer that is watching the channel page where your extension is activated. It will only be populated if the viewer is logged in, and only after the onAuthorized callback has been called. Accessing its properties will otherwise return null.

Much of the information stored here is also present in the extension JWT, and is presented as part of this object for convenience. It is passed to the extension iframe from the client without validation, so it is recommended that you use this info for rendering conditional UI elements, and that you pass the JWT to your EBS for validation if you are using any of this information to grant users permission to take privileged actions within your extension.

opaqueId

window.Twitch.ext.viewer.opaqueId: string

The opaque id of the viewer.

id

window.Twitch.ext.viewer.id: string | null

The Twitch ID of a linked viewer. null if the viewer has not opted to share their identity with the extension.

role

window.Twitch.ext.viewer.role: string

The role of the user. See the JWT schema for possible values.

isLinked

window.Twitch.ext.viewer.isLinked: boolean

Provided as a convenience to check whether or not a user has shared their identity with their extension

sessionToken

window.Twitch.ext.viewer.sessionToken: string

The encoded JWT. This is the same as the token property of the authData parameter that currently gets passed to the onAuthorized callback.

helixToken

window.Twitch.ext.viewer.helixToken: string

The JWT that can be used for front end API requests. For more information, see Using the Twitch API in an Extension Front End.

subscriptionStatus

window.Twitch.ext.viewer.subscriptionStatus: SubscriptionStatus | null

Subscription status will be an object containing information about the viewer’s subscription. The SubscriptionStatus object will have the following properties:

The value of subscriptionStatus will be null if the user is either not a subscriber, or opting not to share their identity. The value will also be null if the extension otherwise doesn’t have subscription capabilities.

onChanged

window.Twitch.ext.viewer.onChanged: void function(callback: Function())

This function binds a callback will be invoked when the viewer’s status changes (e.g. if a viewer subscribes and changes their subscription status).

Client Query Parameters

In addition to the context provided by the Javascript helper’s callbacks, the extension window receives the following query parameters, which indicate information about the extension environment that isn’t subject to change over the frame’s life cycle.

JWT Schema

Example JWT Payload

{
  "exp": 1484242525,
  "opaque_user_id": "UG12X345T6J78",
  "channel_id": "test_channel",
  "role": "broadcaster",
  "is_unlinked": "false",
  "pubsub_perms": {
    "listen": [ "broadcast", "whisper-UG12X345T6J78" ],
    "send": ["broadcast","whisper-*"]
  }
}