Contents

Embedding Everything

Introduction

This guide explains how to embed Live Video with Chat or Video on Demand in a non-Twitch website.

Logging In

Logging in is a seamless, lightweight experience for users of the Twitch Embed Player on non-Twitch websites. Once logged in, a user can chat, follow a channel, or subscribe to a channel. When users try to perform one of these actions, they are prompted to create a Twitch account or sign in to an existing one.

Authentication

Users of embedded Twitch are authenticated in the same way as users of the Twitch website - that is, with the same authentication flow.

Overlays

The Twitch embed contains buttons for Sign In, Follow, and Subscribe, in an overlay above the player.

In some cases, clicking a button opens a pop-up window that allows the user to complete the desired action (for example, navigate through the payment flow or create an account). In others, it automatically goes through with the action (such as Following).

The name of the channel being watched is an overlay that appears when you hover your mouse over the player. On embeds, these titles do not link back to Twitch.

Usage

  1. Add a placeholder element with a unique ID to your page, where you want the Twitch embed to render.
  2. Load the Twitch embed JavaScript file.
  3. Initialize a Twitch.Embed object, with the placeholder element ID and options. If your site will be embedded on other domains, you must include them as a JavaScript array of strings under the key parent.
<html>
  <body>
    <!-- Add a placeholder for the Twitch embed -->
    <div id="twitch-embed"></div>

    <!-- Load the Twitch embed script -->
    <script src="https://embed.twitch.tv/embed/v1.js"></script>

    <!-- Create a Twitch.Embed object that will render within the "twitch-embed" root element. -->
    <script type="text/javascript">
      new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat",
        // only needed if your site is also embedded on embed.example.com and othersite.example.com 
        parent: ["embed.example.com", "othersite.example.com"]
      });
    </script>
  </body>
</html>

Embed Parameters

OptionTypeDescription
allowfullscreenbooleanIf true, the player can go full screen. Default: true.
autoplaybooleanIf true, the video starts playing automatically, without the user clicking play. The exception is mobile devices, on which video cannot be played without user interaction. Default: true.
channelstringName of the chat room and channel (live content only).
collectionstringThe VOD collection to play. If you use this, you may also specify an initial video in the VOD collection, otherwise playback will begin with the first video in the collection. All VODs are auto-played. Chat replay is not supported. Example parameters object:
{ video: "124085610", collection: "GMEgKwTQpRQwyA" }
heightnumber or stringHeight of the rendered element, in pixels. This can be expressed as a percentage, by passing a string like 50%. Minimum: 400. Default: 480.
layoutstringDetermines the screen layout. Valid values:
  • video-with-chat: Default if channel is provided, and only supported for live content. Shows both video and chat side-by-side. At narrow sizes, chat renders under the video player.
  • video: Default if channel is not provided. Shows only the video player (omits chat).
mutedbooleanSpecifies whether the initial state of the video is muted. Default: false.
parentstring[]Required if your site is embedded on any domain(s) other than the one that instantiates the Twitch embed. Example parent parameter: ["streamernews.example.com", "embed.example.com"].
themestringThe Twitch embed color theme to use. Valid values: light or dark. Default: dark.
timestringTime in the video where playback starts. Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video).
videostringID of a VOD to play. Chat replay is not supported.
widthnumber or stringMaximum width of the rendered element, in pixels. This can be expressed as a percentage, by passing a string like 100%. Minimum: 340. Default: 940.

Working with Events

To listen to events, create a Twitch.Embed object, then call the addEventListener method on that object:

var embed = new Twitch.Embed('twitch-embed', {
  channel: 'monstercat'
});

embed.addEventListener(Twitch.Embed.VIDEO_READY, function() {
  console.log('The video is ready');
});

Available Events

Event Description
Twitch.Embed.VIDEO_PLAY The video started playing. This callback receives an object with a sessionId property.
Twitch.Embed.VIDEO_READY The video player is ready for API commands.

Programmatic Access

Advanced usage: To provide additional functionality to our API, access specific components with getPlayer(), which retrieves the current video player instance from the Embed, and provides full programmatic access to the video player API.

<html>
  <body>
    <!-- Add a placeholder for the Twitch embed -->
    <div id="twitch-embed"></div>

    <!-- Load the Twitch embed script -->
    <script src="https://embed.twitch.tv/embed/v1.js"></script>

    <!--
      Create a Twitch.Embed object that will render
      within the "twitch-embed" root element.
    -->
    <script type="text/javascript">
      var embed = new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat",
        layout: "video",
        autoplay: false,
        // only needed if your site is also embedded on embed.example.com and othersite.example.com 
        parent: ["embed.example.com", "othersite.example.com"]
      });

      embed.addEventListener(Twitch.Embed.VIDEO_READY, () => {
        var player = embed.getPlayer();
        player.play();
      });
    </script>
  </body>
</html>