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.

General Guidelines 

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 appear in Panel Extension Guidelines, Video Overlay Extension Guidelines, Mobile Guidelines, and Pop Out Guidelines.

Terminology

The following table contains terms you will need to understand when you’re designing an extension. All the terms are specified in the Extensions Manager.

Term  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 Extensions manager and the details page. 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 Extensions manager. The right summary helps them decide to install the 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. 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 Image is the first thing streamers see of your extension. The Extensions manager shows this splash screen in the Discovery tab on a broadcaster’s dashboard. 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.
Screenshot Images are your best tool to help streamers understand how your extension works, if they haven’t seen it on someone’s channel. Provide clear images that display how your extension works.
You are required to choose a General Category for your extension. If your extension fits in more than one category, choose the most appropriate one.

Don’t choose a category that your extension clearly does not match - for example, specifying the “Schedule and Countdowns” category for a Destiny 2 gear extension.
If your extension supports specific games, you can indicate which ones under Game Category. List only those games your extension supports.

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

Simplify Onboarding and First-time Use

Once the extension is configured and installed, simplify onboarding for viewers to increase their engagement. For video-based Extensions, a subtle animation can be used to draw the viewer’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 one that dynamically displays the top cheerers on a stream).

Extensions should not be distracting (remember the <blink> tag?), but it is appropriate to provide small clues; e.g., subtle bounces to indicate interactivity, and brief flashes to indicate state changes. A distracting extension focuses the viewer’s attention on your extension, away from the broadcast. This 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 helps 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 you don’t provide support, Twitch may find it necessary to remove your extension from the directory.

Choose the Right Extension Type

Throughout this guide, we provide guidelines for using different types of Extensions, but in general, consider:

UI Recommendations

Panel Extension Guidelines

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

Follow these guidelines for Panels:

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.

Safe Zones

Mobile Guidelines

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

For guidance, here are some examples.

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: