Tag: extensions

Twitch Extensions: Part 4 – The One Rig to Rig them All?

This week on the Twitch Extensions Series, we are talking out the Developer Rig, what, when and how to use it!

What is the Developer Rig?

The Developer Rig is a downloadable tool, which is available on Windows, Mac and Linux provided by Twitch and found at https://dev.twitch.tv/docs/extensions/rig, which allows the Extension Developer to do a number of things.

A Typical Twitch Extension Developer Rig landing page.

If the Developer is new to building Twitch Extensions, it’ll also provide easy access to a number of Examples, which you can also find of the TwitchDev GitHub, but once you are into building your actual extension, you’ll be able to do the following things!

The typical tasks that Extension Rig provides Access to
  • Interact with the Config Service, if used for your extension, without having to write custom scripts
  • Manage your Bits Products, if your extension uses Bits, the only place to manage your Products and pricing is via the rig
  • View your Extension under a variety of views, and view configurations.

The rig also does some other useful bits and pieces that developer may have a use for, it provides the ability to start/stop both Frontend and EBS/Backend servers/services, that may be needed when local developing an extension. The paths and start commands can be saved with the project, which will save you time when starting Development for the day.

Especially useful for React/Vue and similar JavaScript frameworks you can “one click” start your Webpack server to serve your Extension for example.

The Extension Hello World hosting settings in the Rig

How to use the Developer Rig

The Monetization tab we will cover later when we talk about Bits in Extensions, and the same for the Configuration Service when we cover that!

So we’ll focus on the big thing the Developer Rig does for you.

First the most important thing that developer needs to be aware of when using the Developer Rig, is that whenever you change any settings for your Extension on the Developer Console you need to let the Rig know you did this, and you can do that on “Project Details” and click “Refresh Manifest”. The Project Details section of the Project also allows you to select which Version you are working on, so if you just released Version 0.0.1 and you started Working on Version 0.0.2, don’t forget to update the rig! Otherwise your test Extension Views will show the live and released version of the Extension instead of your in development version!

The Refresh Manifest button.

Normally, if you wanted to Test a Video or Component Extension, the channel that you would want to test the Extension on would have to be live and Streaming, the developer rig negates that requirement.

The Developer Rig showing a functioning Video Extension on an Offline Channel. What dark magic is this?

Editors Note: Added/Updated 18th March: In a similar fashion, you can use the the devleoper rig to simulate mobile/tablet views in various Dimensions without having to have the device in front of you. Naturally when it comes to mobile/tablets you should test your extension on devices if possible!

You can use the Developer Rig to mobile test, without having to have a device of the appropraite size handy.
Creating a Mobile view. Common Screensize options!

Further more if you wanted to see what your Extension looks like to people whom are not even logged into Twitch you can’t test that on Twitch itself, since if you are logged out then you are not a valid member of the Allow List.

Typical Creating a view Modal

When creating a view, the rig will ask you which View Type you want to test, and what “feature flags” you want enabled, these feature flags, which we’ll cover in a later post, will let the Twitch Extension JS Helper know what is and is not available. As a short TLDR: lets the extension know if Bits Support is enabled, whether the extension should show the Bits Usage store in the extension or not for example.

The Viewer Types a view can be

It’ll ask you to set the Channel that the extension is “active on”, and ask you to set “who” is accessing the Extension. So you can easily setup any combination of views side by side, which is handy if you want to test what the extension looks like for different users on one page with a easy “Refresh All Views” button.

Three “primary” View Examples side by side. Logged Out, Logged In, Logged In Shared. In this example the extension doesn’t differentiate between Twitch logged out/in, I should fix that…
The Context options.

Finally the Extension View for a given view lets you easily send test context changes to an extension.

This will allow you to test how your extension reacts to subsequent calls to onContext easily.

onContext which we will cover more in a future post, is very powerful when you need you extension to react/respond to various things that could happen during the lifetime of a session of the page loaded. Do you need to resize your extension when the player changes dimensions? Do you need to show/hide your extension in response to the player controls being visible? Are two examples.

What can’t it do?

So we talked about what the Developer Rig can do for you, but since the Developer Rig is completely optional (except for Bits products management), why would you choose not to use it?

The Developer Rig will let you setup a view, and the user for that view, but it does not let you test Viewer State changes.

This would be, for example, a user whom is logged in on Twitch changing from “logged out of your extension” to “logged in to your extension”, commonly referred to as “Sharing your Twitch ID with the extension”. Or you the Developer calling the RequestIdShare function to prompt the user to login, which results in nothing happening in your Extension.

Bits Development can be somewhat difficult in the rig, in the rig you are limited to the loopback function which isn’t very useful for testing, but we’ll cover Bits testing Scenarios in a future post!

Config Service setting from the JS helper can be interesting in the rig, but thats more down to the helper function argument order rather than the rig! Personally I do all my configuration service work from the API, and we’ll cover that in a future post.

Summary

So that is the Developer Rig and what it can and cannot do for you! You can read more about the Rig in the documentation and if you need help you can join us in #developer-rig on the Developer Discord

Next week I’m not sure what we’ll cover. I think we’ll actually start a little building and testing some features, and some ideas on making your own test Rig to host your front end code, in a way that will help you avoid some pitfalls that we’ve covered in this series so far!

BUT MOTHER I CRAVE VIOLENCE

Well, until I write the next part if you want to read more about the Developer Side of Extensions, you can pop a visit over the to the Documentation or take a look at Twitch’s Introductory Page and you can always join us on the “TwitchDev Discord Server”, visit the Developer Support Page for the current invite link!

Why you think you are good enough to even write blog posts on Extensions? I made a one or two of them Extensions of various types.

Twitch Extensions: Part 3 – The Architecture of an Extension

In Part 2 we spoke a fair bit about “the path and file name of the HTML file you wish to load, it is a relative path to the Testing Base URI/final upload URL”, and this week we will cover why I mentioned that every time!

So, this week The Architecture of a Twitch Extension!

An example of Architecture from Wikipedia, The Pyramids at Gizah - © CC BY-SA 2.0
An example of Architecture from Wikipedia, The Pyramids at Gizah – © CC BY-SA 2.0

Basic Architecture

We have covered before that essentially a Twitch Extension is a “Website” that is iFrame’ed onto the Twitch Page, into an integration slot, but what does that actually look like?

The Twitch Architecture Overview
The Twitch Architecture Overview – According to Twitch

This is the “stack” that represents how an Extension is loaded, to illustrate this, we’ll use FlightSimTrack installed to the FlightSimTrack Twitch channel

  • First we have the Twitch Channel page – the “Browser” above
  • Then the Twitch Extension “supervisor”, this basically handles any handshaking between the outer Twitch and the inner Extension, we can’t cover more about it as it’s not documented anywhere, and that is my theory on what it does! It is mentioned in passing in the documentation
  • Then the Extension itself – the “iFrame” above

Relative path? WHY?

So why “relative path”? Well here is what the URL to the Panel looks like for FlightSimTrack

https://q6gmlap07mpxekhpspevz2sq5xjth7.ext-twitch.tv/q6gmlap07mpxekhpspevz2sq5xjth7/ 0.0.2/78753d6eeea69840398d8e46ff018e3b/panel/index.html?anchor=panel&language=en&locale=en-US&mode=viewer&state=released&platform=web

The first thing we’ll notice is that the index.html is in a sub folder of the domain. And NOW you know why we said “the path and file name of the HTML file you wish to load, it is a relative path to the Testing Base URI/final upload URL” every, single, time. And it’s a common hiccup that Extension Developers run into, a number of people come into the Developer Discord needing extension help, and they either made a mistake packaging the Zip for upload (we’ll cover Upload procedure in a future post), or the developer has used an “absolute” link to a JS/CSS file (starting /style.css or https://example.com/style.css for example, instead of just style.css).

But lets break down this URL, into it’s parts

URL breakdown

https://extClientID.ext-twitch.tv/extClientID/Version/md5OfZip/path_to_file_for_integration_point.html?querystring

We’ll cover the Query string parameters more in a future post, but you can read about them in the Extension Documentation Reference

The most important one to be aware of right now is anchor which tells you which integration slot this is. In this example it’s a panel, and FlightSimTrack’s panel is configured to load panel/index.html for this integration slot.

  • extClientID is obvious, it’s the ClientID of your Extension
  • Extensions live on the domain extClientID.ext-twitch.tv, why a different domain for each extension and separate to Twitch? This prevents any issues with Cookies from the “main” Twitch Website, so there won’t be any session hijacking or other crazy things, you can read a little more on that in the documentation
  • Version – the version of the extension that these files are for
  • md5 of the zip file that was uploaded, during testing you might go to Hosted test/local test (two Stages of the Extension Lifecycle that we’ll cover next week) a few times, so the md5 will change, this is a easy “cache defeat” when you are Hosted testing
  • Final part is the path and html file you specified in the console to load for this integration slot

Asset Hosting for FlightSimTrack
Asset Hosting for FlightSimTrack

The URL structure is the same for every integration point, and all files are considered “public”, which is something to consider when building in things for Channel Moderators to use.

That about covers everything for the frontend

Well, what about the Backend?

Oh you want the backend to do you?

The Twitch Architecture Overview
The Twitch Architecture Overview – According to Twitch again!

First of all it’s important to note than a Backend, also referred to as EBS or Extension Backend Service, is entirely optional, depending on your Extension, what/how it functions or what it does, it might not even need an EBS, either from calling Public API’s or from it being completely self contained.

The SSL Requirement

But for those Extensions that need an EBS, there is essentially one rule, it must serves it’s contents over SSL, this isn’t just good for Security, but is required as the Twitch Website is over SSL and browsers will reject Mixed Content (loading non SSL content from SSL).

So

  • Loading from the EBS? Needs to be https://urltoyourebs/
  • Loading from a Public API? Needs to be https://someapi/
  • Loading from a Websocket? Needs to be wss://somesocket/
  • Loading an image from a CDN? Needs to be https://somecdn/image.png

To illustrate some examples:

  • FlightSimTrack viewer, nothing at all (images are on the Twitch Extensions CDN and map tiles come from map tile vendors over SSL)
  • FlightSimTrack config, EBS lives at https://twitch.extensions.barrycarlyon.co.uk/
  • CohhCarnage Panel Extension, uses an API at https://extensions.cohhilition.com/ and a socket at wss://extensions.cohhilition.com/
  • Dropped Frames video Extension, no API or socket at all, but images from a CDN, usually Twitter/Twitch avatars directly from Twitter/Twitch over HTTPs, it receives from Twitch PubSub only.

You can see that they all all work over endpoints/routes protected by SSL.

We’ll cover how to build a “custom” EBS, and verifying identity in a future post, this week it’s just “Architecture”, the long and short of it, is you are basically just building a Custom API to interact between your front end and backend. A common way I describe Extensions, is as follows

Extensions are a website, where the front end is on a different server to the backend, and you can’t do server side rendering

– Barry Carlyon on “Well what is an Extension anyway!”

Languages

Whilst a Twitch extension is “limited” to HTML and JavaScript, your EBS/Backend API can be in any language you want. But when it comes to examples, samples and boilerplates you’ll generally find them in JavaScript (via NodeJS) or Go, (since Twitch is a “Go House”). We’ll be using NodeJS in this series, merely because it’s potentially the easiest for people to understand and convert knowledge between different languages.

If you want to jump ahead, you can check out the Developer Rig, which will provide you access to a number of Extension Examples, which are also available on the TwitchDev GitHub, or my own Twitch Profile Extension (which demonstrates how to call the Twitch API via an “EBS” proxy), these examples are designed to highlight a specific function of Twitch Extensions, rather than a “practical” example.

Real Certificates only

Naturally this needs to use “real” SSL Certificates, as apposed to self signed, which is “bearable” for testing with. Generally you’ll find Extension Developers will whip out LetsEncrypt as it’s free and easy to setup, and straightforward to setup a testing system.

Summary

So that covers the Architecture of an Extension

Not really sure what else to add, here is a photo of my cat, Sprite.

Sprite has invaded this Blog Post
Sprite has invaded this Blog Post

What about next week?

Next week we will be looking at the Developer Rig and how/when to use it and setting up a Dev environment suitable for developing a Twitch Extension!

BUT MOTHER I CRAVE VIOLENCE

Well, until I write the next part if you want to read more about the Developer Side of Extensions, you can pop a visit over the to the Documentation or take a look at Twitch’s Introductory Page and you can always join us on the “TwitchDev Discord Server”, visit the Developer Support Page for the current invite link!

Why you think you are good enough to even write blog posts on Extensions? I made a one or two of them Extensions of various types.

Twitch Extensions: Part 1 – An Introduction

This is the first part of a I don’t know how many parts series on Twitch Extensions. We’ll cover how to develop them, how to EBS them, some notes on Designing and what to avoid, some practices for after release care, and touch on some marketing ideas/things for your Extension Website.

So since this is the first part, we’ll cover the basics first. What, Where, Who, How, and Why of an Extension

When is Gamora
Why is Gamora

What is a Twitch Extension

A Twitch Extension is basically an iFrame that allows a developer to create anything they want, as long as it fits within the Guidelines set out by Twitch, and of course it’s Terms of Service and Developer Agreements

This can range from MiniGames, to QnA/Polling extensions, to Community information extensions, to game information extensions, or play with the Streamer extensions

Some examples include

  • Sound Alerts – Lets users pick a sound to play on Stream, can be free or utilize bits/channel points
  • Crowd Control – Provides plugins for a variety of games, to allow people to interact with the game, make it easier/harder for the Broadcaster
  • Cardboard.live – Lets viewers see what cards are in your current deck, and check the state of the game board, without having to spam/ask in chat
  • Borderlands 3 ECHOcast – Lets viewers check out your Borderlands 3 character, and let viewers win extra loot for their own character when the Broadcaster opens Red Chests in game
  • Detroit: Community Play – Ask the community to pick/vote on the option when a multiple choice question appears during the game play of Detroit: Become Human.
  • The Cohhilition – A community interaction extension, that provides access to various Community things (in this case for a single channel), without having the viewer leave the comfort of the Twitch page

Some of these descriptions are super simple to cover the salient points and many will do more things than my summary covers

Check out more extensions at Twitch’s own Extension Discovery

Where is a Twitch Extension

Twitch being a live streaming site, provides to the Broadcaster, a page, and that page will consist of a number of elements.

Depending on if the streamer is live or not the elements on the page will vary slightly. If the Broadcaster is live, you’ll land on the video/chat page, if the Broadcaster is not live, you’ll land on a “Home”/index style page

Now the part that we care about is the “Chat”/live view page, and on that page you will find a number of sections

An example of a Twitch Channel Page
An example of a Twitch Channel Page
  • The Video Player
  • The live Chat
  • The Stream information section – The Title and Category
  • A small about the Broadcaster section
  • The Panels section

A Twitch Extension can be added to a couple of these sections, and has 3 main (and two auxiliary) integration points.

The Main Integration points

  • Video Overlay – The Extension can cover/utilize the whole of the video player
  • Panel – The Extension appears in the panels section below the stream, and has width of 318px and a maximum height of 500px
  • Video Component – Basically a panel that appears over the video player but is locked to the right hand side of the player, it can utilize a varied amount of the player space

The “main” integration points are mutually exclusive, an Extension can only occupy any one of those slots at once

The Auxiliary Integration points

An example of a mobile extension on iOS
An example of a mobile extension on iOS
  • Mobile Panel – The Extension is available on mobile for mobile users to interact, it will replace the chat, and dimensions wise basically similar to a panel on PC (in terms of ratio), but you would have to consider landscape views on tablets as well.
  • Panel popout – Panel Extensions can be opened in a new window and can be resized by the user at will

An extension can be in one of the “main” integration points, and the mobile point.

Who is a Twitch Extension

As part of being on Twitch, extensions are able to use a number of Extension Features, as well as doing more “regular” Twitch stuff. You could run a regular chat bot that runs with your extension, the Twitch Extension Timeout with bits does this in order to run the actual timeout commands on users

So aside from the “regular” stuff like chat bots, Twitch Extensions have access to some additional features

  • Bits Support – Allow Viewers, to exchange bits (a digital good) for various “digital goods” inside Extensions, this could range from an extra vote in polling extensions, or picking a victim in “Timeout With Bits”, or a cool cloak for your character in a game. Revenue generate here is split 80/20 between the Broadcaster/Developer.
  • Subscription Support – Allows the Extension to check the subscription status of a viewer on the channel the extension is installed to, avoiding the need for the Extension Developer to get and maintain oAuth access tokens from the Broadcaster “separately” to the install process of the Extension
  • Identitiy Link – Allows viewers to “login’ to your extension, we’ll cover this more in a later post in the series
  • Chat Capabilities – Allow the Extension to send chat messages (via a HTTP POST request), usually used as a notification system to prompt viewers to perform an action in the extension, like a new poll has started, go vote, for example
  • The Configuration Service – We’ll cover this in a later post as well, but it’s a way to store data on Twitch’s server that you can use in the extension, this might be something like, the name of the Broadcasters Character in a game that you would use in an API request to get information about the character
  • Streamer Allowlist – allows the Extension Developer to restrict whom can install the Extension to their channel

We’ll cover each Capability/feature in future blog posts in the series

How is a Twitch Extension

We’ll cover this more, in depth in later posts, a Twitch Extension is a bundle of files uploaded to the Extension CDN (Content Delivery Network). This needs to include your HTML, JS, CSS, and any static images you want to store on the CDN (pretty handy for background images for panel extensions). Twitch has some restrictions on what an extension can load from external sources, but essentially images are fine, CSS/JS is not, CSS/JS must be local/included.

Those files are uploaded to a sub domain of Twitch, into a particular sub folder tree on that sub domain, which we will cover more in depth in a later post, when we talk about building extensions and a suitable way to test them and some related gotchas.

All Twitch Extensions have their bundles uploaded to the Twitch and before they are released (or updated) to the masses, the Twitch Extension Review team will review the Extension, to ensure it works as intended, there is no major bugs effecting activation, the Extension compiles with the Guidelines and Terms of Services, and most importantly contains nothing malicious to interfere with the Twitch website or the viewer using the extension Computer/device

A Twitch Extension is allowed to communicate offsite, the resource just has to be secured over SSL, this is commonly referred to as an EBS or Extension Backend Service, we’ll cover this more later as well!

Why is a Twitch Extensions?

But Why is a Twitch Extension (any use) I hear you cry?

A Twitch Extension provides ways for the Streamers Community to perform rich interactions, without leaving the Twitch Broadcasters page, which means you keep the Viewer watching the Stream or interacting with Chat, with relatively easy access to Twitch API’s, without long additional steps for Viewer Authentication

Summary

That is it for Part 1 in this series on Twitch Extensions, I’ve cover the basic What, Where, Who, How of Twitch Extensions

Parts will either be weekly or bi-weekly, we will see how we go!

BUT MOTHER I CRAVE VIOLENCE

Well, until I write the next part if you want to read more about the Developer Side of Extensions, you can pop a visit over the to the Documentation or take a look at Twitch’s Introductory Page and you can always join us on the “TwitchDev Discord Server”, visit the Developer Support Page for the current invite link!

Were the sub headings supposed to make sense? No not really.

Why you think you are good enough to even write blog posts on Extensions? I made a one or two of them Extensions of various types.