Contents

Getting Started with Extensions

Introduction

Extensions are programmable, interactive overlays and panels, which help broadcasters interact with viewers. With Extensions, the Twitch community can interact in new ways such as heat maps, real-time data-driven overlays, mini-games, music requests, and leaderboards. If you haven’t seen an extension, check out the TwitchDev channel page and view the Twitter Extension in the panels below the video player.

This guide covers the fundamentals of building your first extension. The example allows Twitch viewers to cycle through colors via a visual element added on top of a section of the video player. On the frontend, a user clicks a button that changes the color of a circle. Instead of changing the CSS locally, it calls a backend server for a new HTML color code; we call this the Extension Backend Service (EBS).

We build this sample using the Twitch Developer Rig, a native application that facilitates Extensions development.

If you’re not a developer or just want to know more about Extensions from a business perspective, see https://dev.twitch.tv/extensions.

Extensions & Broadcasters

Extensions installed and activated by a broadcaster are automatically visible to any viewer who goes to the broadcaster’s channel page using a desktop Web browser or mobile device. Viewers can see details about the extension and report an extension for bad behavior.

Broadcasters can browse and install extensions on their dashboard’s Extensions tab. They can find extensions, add/remove them on their channels, and activate/deactivate them. Installing an extension on a channel does not make it active on the channel page. To do that, after broadcasters install an extension, they configure it (if required by the developer), then activate it to make it visible to all viewers.

Types of Extensions

There are several types of Extensions:

Broadcasters can activate up to 6 extensions at a time: 3 panel, 1 video overlay (full screen), and 2 video component (smaller).

Any extension can also support mobile by adding an optional view.

If pop-out control is enabled, the extension iframe has an icon button that viewers can click to pop out the extension into its own window.

Extensions Console & Extensions Manager

To create and manage Extensions, you use two main interfaces:

Enable 2FA

Before you can create an extension, you must enable two-factor authentication (2FA). If you don’t already have it enabled, you can enable it through the Extensions manager or the console. On the console:

  1. Click on your profile (top right), then select Account Settings from the dropdown.
  2. In the Settings window, click the Security and Privacy tab.
  3. Click Enable two-factor authentication, then follow the steps.

Hello World

  1. Download the Developer Rig for Windows, Mac, or Linux, then open the downloaded file to install the Rig.
  2. Launch the rig and sign in with your Twitch developer credentials.
  3. Click Add Project (top left), then Create Project. The first Create New Project setup screen appears.
  4. Fill out the fields on the first setup screen:
    • In the dropdown list, select New Extension.
    • Name your project (e.g., “ Hello World”). Project names must be globally unique.
    • Use the default version, 0.0.1.
    • Under Extension Type, select Video Component.
    • Click Next. The second Create New Project setup screen appears.
  5. Fill out the fields on the second setup screen:
    • Select a folder on your filesystem for your project files.
    • Choose the code to add to your project: select Use Extension tutorial example and click Getting Started.
    • Click Next. The code is pulled from Github and a final Create New Project setup screen appears, indicating your project was created.
  6. Click Get Started. The Project Details page appears.
  7. Fill out the fields, to have the rig host your extension frontend files and backend service locally:
    • For front-end files, click Run Front End.
    • For back-end files, click Run Back End.
    • Do not change any pre-populated fields.
  8. Test:
    • Click Extension Views (left nav pane). By default, this simulates a broadcaster’s channel.
    • Add a video-component view of the extension: Click Create New View, ensure the view type is Component, and give it a label like “main.”
    • Click Save.
  9. You should now see the Hello World extension running on a simulated video player. Experiment with the extension by cycling through colors with the button in the extension.

A Closer Look

Now that you’ve built the app, let’s explore how it works.

Frontend

The extension frontend comprises HTML files for the different extension views (types of Extensions), as well as corresponding JavaScript and CSS files. The frontend for the Hello World extension has:

The HTML files allow the extension to be run as any type of extension. Here, we use a video-component extension, so video_component.html is rendered.

The frontend logic is handled by viewer.js. The two core functions are authentication and GET/POST requests to our EBS. On first load, twitch.onAuthorized enables the button, sets our authentication token, and dispatches the GET request to retrieve the initial color.

twitch.onAuthorized(function (auth) {
   // save our credentials
   token = auth.token;
   tuid = auth.userId;
   // enable the button
   $('#cycle').removeAttr('disabled');
   setAuth(token);
   $.ajax(requests.get);
});

When the viewer presses the button, the onClick handler creates a POST request to the /color/cycle/ endpoint. On a successful response, updateBlock() is called, passing the payload which contains a new hex value. updateBlock() simply renders the new hex value using CSS.

$('#color').css('background-color', hex);

Backend

The EBS:

Our backend logic is contained in backend.js. Using hapi, we spin up a light web server. Hapi handles hosting our GET and POST /cycle/color endpoints. These endpoints then route to colorCycleHandler or colorQueryHandler.

Hapi makes this mapping easy:

// Handle a viewer request to cycle the color.
server.route({
   method: 'POST',
   path: '/color/cycle',
   handler: colorCycleHandler
});

// Handle a new viewer requesting the color.
server.route({
   method: 'GET',
   path: '/color/query',
   handler: colorQueryHandler
​​​​​});

colorCycleHandler and colorQueryHandler have similar logic, but colorCycleHandler also produces a new hex value. First, these functions authenticate the request with verifyAndDecode. Then we use the channelColors array (indexed by channelID) to store hex values. After producing a new color, we save it back to the array and return the value to the frontend.

function colorCycleHandler (req) {
   // Verify all requests.
   const payload = verifyAndDecode(req.headers.authorization);
   const { channel_id: channelId, opaque_user_id: opaqueUserId } = payload

   // Store the color for the channel.
   let currentColor = channelColors[channelId] || initialColor;

   // Rotate the color as if on a color wheel.
   verboseLog(STRINGS.cyclingColor, channelId, opaqueUserId);
   currentColor = color(currentColor).rotate(colorWheelRotation).hex();

   // Save the new color for the channel.
   channelColors[channelId] = currentColor;
   return currentColor;
}

Another Way to Create Extensions

  1. Visit your Extensions developer console and login with your Twitch account credentials.
  2. If 2FA is not yet set up, you’ll see a prompt: click Enable 2FA, set up the authentication, then click Done to return to the console.
  3. Click Create Extension. The Start an Extension page appears.
  4. Fill in Name your Extension, then click Continue. The Versions page for your new extension appears.
  5. Complete the fields. For your convenience, version number and all optional fields are automatically populated.
    • Type of Extension — (Required) Select Video - Component.
    • Version Number — (Required) Leave this as 0.0.1.
    • Summary — (Optional) This will be viewable by broadcasters and viewers. It should be 1-2 brief sentences describing what your extension does. To provide more detail, use the Description.
    • Description — (Optional) More detail than the Summary about the functions of your extension.
    • Author Name — (Optional) The full name of the extension author or organization that will receive credit on the Extensions manager.
    • Author Email — (Optional) Contact information for the extension creator. This is used to contact the developer with information about the extension’s life cycle (e.g., reject/accept notifications). Twitch will never reveal this email to anyone on the site.

      If you provide this, you’ll get a verification email soon after creating the extension version. Be sure to check your email, as you need to verify ownership of the author email address.
    • Support Email — (Optional) Public contact information for support-related queries from broadcasters.
  6. Click Create Extension Version. The Status page of the Extensions manager appears, showing your new extension. See Extensions Life Cycle Management for details about adding more metadata about your extension and moving it through the Extensions life cycle.

What’s Next

To learn more:

Docs Status Support Showcase Blog