Getting Started with Extensions
Welcome to developing Extensions!
This guide shows you how to onboard to be a 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.
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. 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.
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).
To get your first extension running locally on your machine, you’ll use the Twitch Developer Rig. The Developer Rig is an open-source tool, maintained by Twitch, which enables you to easily get started developing Extensions. As an extension developer, you can use the Rig to:
- Test locally against mock endpoints, using the Developer Rig in “Local Mode.” You do not need to go through Extensions onboarding to do this. This is the fastest way to get started.
- Quickly generate and run a Hello World sample. You can use this sample to understand how Extensions are laid out and how to interact with the rig. The sample app can serve as scaffolding for your extension.
- Test locally against Twitch production endpoints (once you have created an extension on Twitch). This local access to an initial set of Twitch endpoints gets you as close as possible to the live experience, simplifying your integration testing.
You can test across the views you need to support (panel, overlay, etc). And you can test these views with different viewer and broadcaster states (e.g., signed in, anonymous, broadcaster, linked, and unlinked).
Before you can test against production endpoints in the rig, you need to complete Extensions onboarding, described below.
Using the Developer Rig
To begin using the Rig, clone the GitHub repository here. The README.md file in the root directory contains instructions to:
- Get the Rig running locally.
- Configure an extension for the Rig.
- Retrieve extension scaffolding and boilerplate code.
When you are ready to test your extension on Twitch, against production endpoints, you need to complete the Extensions developer onboarding process. This will allow you to create an Extension online on Twitch and host your assets on Twitch’s CDN.
Extensions allow you to run your code on the Twitch website, in end user’s browsers, so it’s important that we verify our developer’s identities to help guarantee safe experiences and maintain end-user trust. During onboarding, we require your tax and financial information, so we can validate your identity.
Fill out the onboarding form carefully. To change information later, you must redo the entire form.
Note: If you are already a Twitch partner or affiliate, you do not need to fill out the form. See below.
Procedure for Non-Twitch Partners/Affiliates
To begin the onboarding process:
- Log into the developer site, https://dev.twitch.tv.
- In the top row, click the Dashboard tab.
- In the Extensions box, click the GET STARTED button, to let Twitch know you are ready to onboard.
- Go to the onboarding process, by doing one of the following:
Complete all four sections of the form:
Register as a developer.
Complete the fields with information about the legal entity that owns the extension. This information must exactly match your tax information and financial information, so make sure it is correct.
Each legal entity can have only one Extensions developer account. If you have multiple individuals under one legal entity, please do not complete the onboarding multiple times; instead, have all your users utilize your one onboarded Twitch account.
Agree to the Twitch Extensions Developer Agreement.
If you are under 18, this section asks your parent or legal guardian to agree to the agreement on your behalf. Your parent or legal guardian must enter his/her full legal name, check the box, and click Agree.
For help interpreting the contract, please contact your attorney. (Twitch is not equipped to help with this.)
Complete two tax interviews, for royalty tax and service tax. The two forms are very similar but used for different purposes. Both need to be filled out accurately.
Since Twitch is a subsidiary of Amazon, we use some Amazon tools to help Extensions developers get registered, including the tax-information forms. For definitions of individual fields, see the Amazon Tax Information Interview Guide.
For help with this section, please contact your tax professional. (Twitch is not equipped to help with this.)
Provide financial information, to finish the process of validating your identity. Also, providing this information enables you to participate in monetization features that may become available. In this section of the form, you select how you want to be paid.
On the Payment Method screen, we recommend you select Hold My Payments. You can modify this selection later if desired.
In this step, we request some personal financial information so we can validate your identity, as mentioned above.
This section may ask you for additional information. If you get this prompt, please submit a scanned copy of your government ID, such as a passport.
When you finish providing all requested financial information, the approval process will begin. It can take up to 48 hours. If you are approved, you will get a notification email. If you are not approved, information is provided in Extensions Developer Onboarding; return there if you do not get the approval email within 48 hours.
Procedure for Twitch Partners and Affiliates
Follow these steps:
- Log into the developer site, https://dev.twitch.tv.
- In the top row, click the Dashboard tab.
- In the Extensions box, click the GET STARTED button.
You will receive an email enrollment confirmation very soon (within a minute).
- After the email arrives, reload the dashboard. The GET STARTED button is replaced with VIEW EXTENSIONS. You can start developing now!
Changing Information After Onboarding
To change your payment method, select Change Payment Method.
To change other information, on the Extensions Developer Onboarding main menu, click Start Over. This clears any information you have in our system, so you must complete the entire onboarding process again.
Create Your Extension
When you create your extension on Twitch, 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 information later, before you submit your extension for review.
Log in to the Twitch developer site with your Twitch ID.
Navigate to the Extensions dashboard, then click Create Extension.
- Complete each field in the Create an Extension form:
- Name — The name of your extension. This cannot be changed later, so double-check the spelling.
- Type of Extension — The type(s) of your extension (e.g., Panel, Video Overlay, Video Component).
- 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 stage of the extension life cycle. You will get a verification email soon after creation.
Congratulations, you’re well on your way to creating an extension! Be sure to check your email, as you will need to verify ownership of the provided author email address.
To change information later, click the Settings tab after your extension is created. These fields are not version specific: they apply to all versions of the extension.
You’re well on your way to building and launching an extension on Twitch.
Before you start developing your own extensions, read Required Technical Background for Extensions.
Next, consult other Extensions documentation for complete information on how to:
- 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.