Update: Please read the announcement for these changes in production which includes a guide for updating your existing component Extensions.
Twitch is redesigning the component Extension anchor in the video player in order to address usability issues and create a more consistent developer, creator, and viewer experience. We are going to be implementing a design that fixes the location of component Extensions to the side of the player, initializes them in a collapsed state, and only allows for a single component to be displayed at a time. This redesign changes the interaction model of component Extensions, and we highly encourage developers to update the user interfaces of their component Extensions accordingly. We will be rolling out these changes in early access to developers, so that they can start building within the new framework and be ready for when the design update rolls out to viewers.
Since we launched component Extensions last year, feedback from viewers, creators, and developers have indicated to us that the experience of creating and interacting with component Extensions is confusing and hard to predict. Some of the pain points we have discovered are:
- Viewers struggle to understand what elements of a stream are – and aren’t – Extensions.
- Viewers have difficulty comprehending an Extension’s purpose or how to interact with it.
- Extension positioning is different from channel to channel.
- Broadcasters are unsure how Extensions will appear on their stream and how viewers will be able to interact with them.
While the ability to use multiple Extensions in the video was one of our most requested features following the launch of Extensions in 2017, at the end of 2018 only 12% of channels using a video Extension had more than one active simultaneously.
These challenges led us to explore alternative implementations that can make the video Extension experience more consistent and approachable across channels. Our goal with this design is to create an easy to understand and easy to use model for Extensions in the video player across all channels. We believe that by providing a more consistent and intuitive experience across Twitch, viewer engagement and broadcaster adoption of Extensions will increase, allowing Extensions to create more value for both viewers and broadcasters.
To solve these problems, we are proposing a “Extensions sidebar” design with all component Extensions hidden by default on channel load. Components will be expandable by clicking their icon in the Extensions sidebar, which is presented with a location and styling that is more prominent than the existing Extension icons in the video player’s bottom controls. Components will always display in the same location when opened – connected to the Extensions sidebar. A component can be closed by clicking on its icon again or on a standardized close button outside of the iframe. Extension information and functionality like identity linking will be available through a “cog” menu outside of the iframe when the Extension is open. A viewer will only be able to view a single component Extension at a time. Clicking a new component will automatically collapse the currently open component if there is one.
Overlay Extension functionality will remain largely unchanged and will still be visible by default on channel load. Overlay Extensions may need to account for the new non-interactive region created by the Extensions sidebar in their design.
On player controls hover
Tooltip for hovering on an Extension
An open component Extension
The overlay Extension menu
The full component Extension experience
What Changes Do I Need To Make To My Extension?
The new design eliminates the need for Component Extensions to have a “collapsed” or “minimized” state, as all components will collapse into the Extensions sidebar when they are hidden. It also no longer requires that Extensions present a “hovered” state, as it is expected that whenever a user’s cursor is over an Extension frame that they have intent to interact with it already. As a result of this, it will be expected that component Extensions utilize all of their allocated space when visible. Component Extensions that do not meet this requirement will be rejected during review.
An example of a “collapsed” state that should no longer be used by component Extensions
Component Extensions will no longer need to provide a “Close” button that collapses the Extension via the
minimize() function, as this will be provided as native UI in the Twitch player.
This “X” button will no longer need to be part of the component, close functionality is now handled by the standardized header bar.
The way the sizing of a component Extension is defined will also be changing. Extensions are currently sized with height and width values that are expressed as percentages of the corresponding player dimension. This proved challenging to understand as it was hard to conceptualize how the values for height and width related to each other. We are proposing the following new scheme for specifying the size of a component:
|Target Height||The desired height of the Extension expressed as a percentage of the available space in the player. “Available” space here means the space between the top and bottom controls in the player, minus the height of the new component top nav.|
|Aspect Ratio||A set of 2 integers (Width and Height) representing the desired aspect ratio of the Extension|
For example: a component with a target height of 25% and an aspect ratio of 4:3 will render at a height of 250px and a width of 333px when the available vertical space is 1000px.
Component Extensions will always maintain the given aspect ratio and will attempt to maintain the target height provided, except in cases where the player is either extremely large or small. In those cases, they will either stop scaling with the player or be hidden respectively. The function of the “Zoom” and “Zoom Pixels” options will remain unchanged.
We will also be adding a new field to the Extension manifest titled “Viewer Description”. This field should be a short summary that explains to a viewer what your Extension does (in contrast with the existing summary and description fields, which are to be directed more at broadcasters). This description will be displayed to viewers in the Extension details menu. This field will be required for all future versions of Extensions after we launch this redesign. Existing Extensions that have not added a viewer description will fall back to displaying the existing broadcaster summary field.
update_user_extensions API endpoint will no longer require the x and y parameters for activating component Extensions. If these parameters are included, they will simply be ignored.
Lastly, we are removing the expectation in our guidelines that Extensions in video player anchors don’t perform any background processing while their visibility is false. Given that component Extensions now will go through the initialization process while hidden and will be expected to display up-to-date UI immediately upon being shown, we feel that this policy is too restrictive. Note that we still expect Extensions in mobile views to continue to minimize background processing when hidden.
Migration Plan and Timeline
Phase 1: Design Query Param + Dev Rig (May 15)
We will provide component Extensions with the ability to know which design they are running in with a URL query parameter
legacyComponentDesign that will be passed to the Extension frame. If this parameter is present, developers should render their Extensions as they have up until now. If not, the Extension will be expected to follow the new design recommendations outlined above.
In addition to this, we will be updating the Developer Rig with a new view type for the new Component Extension design, so developers can begin testing their UI updates. The legacy Component design will be passed the
legacyComponentDesign param within the Rig view as outlined above. The ability to use the new sizing scheme in your Extension manifest will not yet be available, but you will be able to specify a size for your component in the “Component (New)” view and have your component render with those values rather than the size specified in your manifest.
Phase 2: Beta Twitch Web Client + New Size Fields in Manifest (
June 15 June 19)
After we roll out the Rig changes, we will allow developers to opt in to a beta version of the component Extension redesign. This will allow developers to test the migrated versions of their Extensions on the website itself. The details of how to opt in will be presented closer to this date.
This will pair with the ability to specify the size of your Extension using the new size description values in your Extension’s manifest. For a period, we will require both to be specified, and users of the production client will still see your Extension sized in terms of the old “Aspect Height” and “Aspect Width” definitions while you are able to test with the new sizing scheme in the beta client. All existing Extensions’ initial values for the new sizing scheme will be pre-set with values that match their original size as closely as possible.
Once you have updated and tested the new UI you display when the
legacyComponentDesign parameter is not present, you can release your new Extension version at any time. As long as your Extension handles the parameter properly, your Extension will display your new UI when we go to launch the redesign.
Phase 3: Launch (
July 15 Late July)
After the end of the two-month beta period, the new design will be released to all users. After this point, no Extensions will receive the
legacyComponentDesign flag, and it will be safe to remove any logic that depends on it and deprecate Extension UIs designed to work with the old anchor design. We will also be removing the legacy design from the Developer Rig at this time. Any Extensions that have not been updated to comply with the new design policies 30 days after launch may have component support disabled until they are updated.
Component Extensions now no longer display to viewers by default
We recognize that in this new framework, components will have a decreased ability to show information to viewers who take no action (by default). However, our research indicates that the consistency and ease of understanding created by the Extensions sidebar will improve overall comprehension and engagement with component Extensions in the long term. Preliminary user testing has shown us that viewers better understanding where to look for and how to interact with component Extensions when they are presented in a consistent and standardized way, generating higher overall engagement with valuable Extension experiences.
Additionally, by more clearly differentiating the functionality and use cases for overlay and component Extensions, developers can create more effective Extension experiences for each anchor and broadcasters can better understand how an Extension will change the content on their page, increasing overall willingness to use components on their channel.
Alternative above-the fold anchor point
As part of our research, we realized one of the primary motivations for having an extension in the video player is so that users can discover it without scrolling down into the channel’s panels section. We briefly considered creating a new anchor point that exists “above the fold” and outside of the video player, but as we researched this path, we quickly discovered the importance of continuing to have these extension experiences travel with the video and into watching modes like theater and fullscreen.
Dynamically resizing iframes
One of the major pain points we are attempting to address is viewers not understanding when a component Extension in a “collapsed” state was still overlapping with elements of an overlay Extension. We considered granting developers the ability to dynamically size a component’s frame so that this problem of invisible iframes wouldn’t block interaction with other Extension elements. We decided against this approach because of the added complexity to developers in specifying the size of their component Extensions, and because it still failed to address the problem of many extensions being unrecognizable by viewers. We believe that for component extensions to be successful, they need a consistent experience across channels in order for viewers to be able to identify a glance where to find extensions and what they add to a stream.
We appreciate and welcome any feedback or questions you might have about these changes via comments in this thread. Watch the Twitch Developers website for further updates. We will be making announcements there as well as in this thread as we roll out the various stages of this redesign.