Getting Started with Extensions
Welcome to developing Extensions!
This guide shows you how to get started as an Extensions developer and run your first Hello World extension within the Twitch Developer Rig.
If you have an issue, need more information, or have a question about anything in this guide, please visit the Extensions category of the Twitch Developer Forums.
If you’re not a tech developer or just want to know more about Extensions from a business perspective, see https://dev.twitch.tv/extensions.
What Are Extensions?
Extensions are interactive web apps that run on a broadcaster’s channel, either overlaying the video or below it in panels. Extension developers can build experiences ranging from broadcaster/community tools, to data driven overlays, to interactive apps that let the audience play in the game. These experiences bring viewers and broadcasters together, creating new ways to interact on Twitch.
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:
- A panel extension appears in the panel area below the video player. Panel extensions remain active even when the channel is not live.
- A video-overlay extension renders on top of the video player as a transparent overlay. This type of extension is viewable only when the channel is live.
- A video-component extension renders on top of both the video player and any video-overlay extensions. Component extensions take up only part of the screen and can be hidden by viewers. This type of extension is viewable only when the channel is live.
Broadcasters can activate up to six 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. (For details, see Mobile Support in Building Extensions.)
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. For details, see Pop-Out Extensions.
Extensions Dashboard & Extensions Manager
To create and manage Extensions, you use two main interfaces:
- The Extensions developer dashboard. From here, you can start the process of creating a new extension, view and clone your extensions, and go to the Extensions manager for a specific extension version.
To get to the dashboard: Visit https://dev.twitch.tv/dashboard/extensions and login with your Twitch ID.
- The Extensions manager. This is where you manage a specific version of an extension. From here, you can provide details about new Extensions (to complete the creation process started in the Extensions developer dashboard), move your extension version through the test/review/release lifecycle, and manage existing extensions. Details about the Extensions manager are in Managing Extension Versions.
To get to the manager: On your Extensions developer dashboard, click Manage next to any version of any extension.
Before you can create an extension, you must enable two-factor authentication (2FA). You can do this through either the Extensions manager (when creating your first extension, as described below) or your Twitch developer dashboard, as described here:
- On your Twitch developer dashboard, click on your profile (top right), then select Account Settings from the dropdown.
- In the Settings window, click the Security and Privacy tab.
- Click Enable two-factor authentication, then follow the steps.
Hello World & the Developer Rig
To get your first extension running locally on your machine, you’ll use the Twitch Developer Rig. The Developer Rig is a tool built in Electron and maintained by Twitch, which enables you to easily get started developing Extensions. The current version of the rig is in beta. As an extension developer, you can use the Developer Rig to:
- Create and run an extension project, using either your extension code or example templates in the rig. An extension project is a combination of an extension manifest (metadata) and extension code. You create an extension manifest on the dev site, and you can make this part of your extension project in the rig.
- Quickly run a Hello World example, to see how Extensions work and how to interact with the Developer Rig.
For more information, see the Extensions Developer Rig document.
To start using the Developer Rig:
- Download the version for Mac here or Windows here.
- Install the rig just like an app.
- Launch the rig and sign in with your Twitch developer credentials.
- Create a project, using an extension manifest you created on the Twitch dev site (links are in the rig, or follow the procedure below).
- Run your extension in the rig.
Create Your Extension Manifest
When you create your extension manifest on the Twitch developer dashboard, you’ll need to fill out the following information. The most consequential information is the name, type, and author email; if needed, it’s okay to fill in dummy info in the other sections for now.
You can update manifest information later. To update the manifest any time before you submit your extension for review, your extension must be in local test mode. (See Extension Life Cycle and Testing Your Extension.) To update the manifest after the extension is released, you need to create a new version of the extension.
- Log in to the Twitch developer site with your Twitch ID, then navigate to the Extensions dashboard.
- If your account is not already set up for two-factor authentication, Enable 2FA appears. Click it, set up the authentication, then click Done to return to the dashboard.
- Click + Create Extension.
- Complete each field in the Create an Extension form:
- Name — The name of your extension.
- Type of Extension — The type(s) of your extension (e.g., panel, video overlay, video component, mobile).
- Summary — This will be viewable by broadcasters on the extensions listings page in the Extension Manager. It should be 1-2 brief sentences describing what your extension does. To provide more detail, use the Description field.
- Description — More detail than the Summary about the functions of your extension.
- Author name — The full name of the extension author or organization that will receive credit on the Extension Manager. This can be changed later.
- Author email — Contact information for the extension creator. This is used to contact the developer with information about the extension’s lifecycle (e.g., reject/accept notifications). Twitch will never reveal this email to anyone on the site.
- Support email — Public contact information for support-related queries from broadcasters.
(Optional) Add a logo for your extension. This must be 100px x 100px. Do not use Twitch or Glitch logos. If you do not have a logo, a default logo will be assigned.
- Click Create Extension to create your extension manifest, containing metadata about your extension. Your extension is now in the Local Test state of the extension life cycle.
That’s it! Soon, you will get a verification email. Be sure to check your email, as you need to verify ownership of the author email address.
You’re well on your way to building and launching an extension on Twitch.
To learn more about Extensions, visit:
- Our page for streamers. This includes a video showcasing examples of Extensions available for broadcasters today.
- Our Extensions video collection. For a list of all Extensions videos, click on the title of any video (top left in the video window).
- The Twitch developer forum for Extensions.
- The Extensions Developer Sandbox, where you can live edit a simulated extension in the browser.
Before you start developing your own extensions, read the rest of the Extensions documentation set on the Twitch developer’s site. Start with Required Technical Background for Extensions. Next, consult other Extensions documentation for complete information on how to:
- Learn more about the Developer Rig.
- Design your extension following Twitch’s design best practices and adhering to Twitch’s guidelines and policies.
- Build your extension. While you are developing, continually and thoroughly test.
- Prepare and submit your extension for review.
- Once it is approved, release your extension, then maintain it over time as needed.
- Use Bits in Extensions to activate specific actions and “micro-experiences” in your extensions, in exchange for a viewer’s Bits used within the extension.
Code samples are available on GitHub.