Contents

Designing Extensions

Introduction

If you are just getting started with Extensions, use the recommendations in this guide to put your best foot forward for streamers. If you already shipped an extension, use this guide to take your extension to the next level; e.g., with other extension types, such as panel or video overlay.

All Extensions

Extensions provide new ways to interact on Twitch, so we provide guidelines to help ensure your experiences are harmonious with the overall Twitch experience. The guidelines in this section apply to all extension types. Guidelines for specific extension types follow this section.

Use “Discovery” to Introduce Your Extension to Streamers

The Twitch Extensions directory showcases all Extensions available to broadcasters, letting them see examples of each extension as it would appear on their channels as a panel, video overlay, or video component.

Discovery page showing extension names, companies, summaries, and splash screens

Follow these guidelines:

Item Guidelines
The extension’s name is how you define what streamers know it as. The name can show up in many places, such as the Extension Manager and the details page. You provide the name when you first create your extension.

Use a descriptive name that allows streamers to understand what your extension does at a glance.

Don’t change the name, unless the nature of the extension has changed significantly.

Don’t use words unrelated to your extension, just to boost your extension in search results.

The summary is a short description of your extension that streamers see when hovering over the discovery splash screen in the Extension Manager. The right summary helps them decide to install the extension. You provide the summary when you first create your extension.

Use as a selling point the most important benefit to a streamer using your extension.

Be concise. Don’t try to explain everything your extension does in the summary.

The description is a longer explanation of your extension. It appears on the details page. You provide the description when you first create your extension.

Write the description from your streamer’s viewpoint. Let streamers know how your extension will improve and enhance their channels.

Consider writing in the second person (using you/your), to more closely associate with streamers.

Don’t be too verbose.

The discovery splash screen is the first thing streamers see of your extension. The Extension Manager shows this image in the Discovery tab on a broadcaster’s dashboard. You provide this image when you submit an extension for review.

Don’t use a lot of text; that overwhelms the image.

Avoid having too much detail in the image, to maximize visibility.

Avoid transparency in your PNG.

Screenshots are your best tool to help streamers understand how your extension works, if they haven’t seen it on someone’s channel. You must include one or more screenshots when you submit an extension for review. Provide clear images that display how your extension works.
You are required to choose a general category for your extension, when you submit it for review.

If your extension fits in more than one category, chose the most appropriate one.

Don’t choose a category that your extension clearly does not fit into. Example: Specifying the “Schedule and Countdowns” category for a Destiny 2 gear extension.

If your extension supports specific games, you can indicate which ones in the Extensions Manager: under Settings > General, in the Game Category field, select up to 15 games your extension supports. (Start typing and the field will list available options.) List only those games your extension supports.

Make Onboarding and First-time Use Easy and Fast

Once the extension is configured and installed, make onboarding for viewers seamless, to increase engagement. For video-based Extensions, a subtle animation can be used to draw the user’s eye to engage with your experience. For panel Extensions, consider a splash screen explaining the extension’s capability (unless it is an informational extension, such as dynamically displaying the top cheerers on a stream).

Extensions should not be distracting (remember the <blink> tag?), but it is fair game to provide small clues; e.g., subtle bounces to indicate interactivity and brief flashes to indicate state changes. A distracting extension forces the viewer’s attention on your extension, away from the broadcast. The paradigm is still new and might require a little training of Twitch viewers.

If your extension requires some setup by viewers, consider disclosing those steps progressively throughout the experience: ask for only the information you need to get to the next step, rather than all the information up front. This includes asking for authorization from a viewer to share the viewer’s user name with the extension. Ask the viewer to authorize only when the extension requires the user name to continue. Also, it helps to explain to the user the value of the extension and why the extension requires user names, before asking for authorization.

Amplify Broadcasters

First and foremost, fans come to Twitch to engage with broadcasters. If broadcasters find that an extension will help grow their channels, they are more likely to install it. Some Extensions may provide utilities that are widely applicable to many broadcasters; e.g. leaderboards and top viewers. Other Extensions, like those made for a specific game, will have smaller audiences; that’s okay! Regardless, serving broadcasters first increases the likelihood of your extension being a part of their channel’s experience.

Panel Extensions have the unique capability to be always on, regardless of whether the streamer is online. We provide a JavaScript helper function that lets you see if a broadcaster is online, which you can use to change the experience of your extension. For example, a panel extension showing a leaderboard of viewer engagement could filter by the users attending the broadcast, versus overall top engagement when the streamer is offline.

Complement the Stream UI

The channel stream real estate may limit how your extension appears or is placed on the video. Top streamers often leverage broadcasting studio apps (like OBS) to create brand elements, animations, and live content to augment the broadcast. Given the shared space that Extensions occupy, assume that a streamer is leveraging tools like OBS to create a canvas that may interfere with the area where your extension UI will appear. Following this assumption, Extensions should include configuration options for broadcasters to align the experience with their channel’s branding. Consider allowing color, font and other UI customizations, to ensure your extension blends in with the overall experience.

Consider including extension capabilities that can be minimized or hidden by users, and only take up areas of the real estate that make sense given the content a streamer broadcasts. For example, a Hearthstone stream has most of its action in the middle of the board, so occupying the top right of the video will ensure your extension does not interfere with the game’s content. However, if your extension augments the information about the game and may require placement closer to the content on video, make sure it can be collapsed, to ensure you limit its interference with the content/game.

Fail Gracefully and Take Feedback Well

With potentially hundreds of thousands of users interacting with your extension every day, there is a chance your extension will have issues. Even relatively simple Extensions (like those that display the gear a streamer uses to create a broadcast) can have hundreds of failure points. Just like any app, anticipating general failures goes a long way to build user trust.

Apps should handle 404 or 500 errors by providing ways for viewers to provide feedback and leverage some other part of your extension. Apps that fail to retrieve data also should allow users to provide feedback. Streamers control the placement and use of Extensions, so your extension should be prepared to accept feedback directly. If there is no option for support, that could lead to a bad experience for Twitch and risk your extension being pulled from our directory.

Choose the Right Extension Type

Throughout this guide, we provide some guidelines for the best uses of different types of Extensions, but in general, consider:

UI Recommendations

Panel Extensions

Example panel extension, a calendar schedule

A panel extension appears in the panel area below the video player. Panel Extensions remain active even when the channel is not live.

Video-Overlay Extensions

Video-overlay Extensions are meant to enhance the viewer’s experience, so be aware that each extension element covers valuable real estate.

Mobile

When designing mobile Extensions, consider the basic principles of any mobile application:

For guidance, some examples are given below.

Optimized Extension Example

Extension, unoptimized and optimized for mobile

Here are notes on the optimizations:

Notes on mobile optimizations

Alignment Example

Mobile extension alignment

Phones (Landscape View)

Phones, landscape view example

iPhone X (Aspect Ratio: 19:5:9)

iPhone X example

Pop Out

To optimize the layout of pop-out Extensions, consider the following: