Twitch tracking in Google Tag Manager

New in 2.0.0. Google Tag Manager for WordPress reports how your visitors watch the Twitch streams and videos embedded on your site. Starting, pausing, seeking and finishing become data layer events, and the plugin also reports when a channel goes live or drops offline while someone is watching.

This page describes GTM4WP 2.0.0 and newer. Twitch tracking did not exist in the legacy 1.x versions of the plugin.

The option is experimental and carries an Experimental badge in the plugin settings. It rebuilds your embed to make tracking possible, which is described below, so test it on a page you can check before you switch it on everywhere.

Turning Twitch tracking on

Open the plugin settings, go to the Media events section, expand the Media players group and check Twitch events. The option is switched off by default.

Which embeds are detected

The tracker looks at every iframe whose src contains player.twitch.tv and reads the channel, video and collection parameters from that address. An embed carrying none of the three is left alone, because there is nothing to identify.

Tracking depends on the Twitch Embed API, which is only requested once the tracker has actually found a Twitch embed on the page, so a page without one never contacts Twitch. If a consent manager, an ad blocker or a network error keeps that script from loading, the embed is left exactly as it is and nothing is measured.

A player that is in the page when it loads is wired straight away. One inserted later, for example in a popup, a lightbox or a section loaded by AJAX, needs the Track dynamically inserted players option in the Advanced group as well.

Your embed is rebuilt, not wrapped

Read this one before you switch the option on, because it changes the markup on your page.

A plain Twitch iframe cannot be listened to after the fact. Twitch only reports playback events on a player that its own Embed API created, so the plugin removes your iframe and builds a fresh Twitch player in its place, pointing at the same channel, video or collection.

Five things survive that swap: the channel, the video, the collection, the width and the height. Everything else on the original iframe is gone. A CSS class your theme relied on, an inline style, a title attribute, a data- attribute added by a page builder, an allowfullscreen setting, a parent parameter you tuned by hand: none of them carry over. If your Twitch embeds are styled or scripted by anything on your site, check those pages after you enable the option.

Playback states

The gtm4wp.mediaPlayerStateChange event fires with these values in the mediaPlayerState variable:

mediaPlayerState	Fires when
`play`	Playback starts.
`pause`	The visitor pauses the player.
`ended`	The video reaches its end.
`seeked`	The visitor jumps to another position.

There is no buffering state, because the Twitch player does not report one.

Player events

The gtm4wp.mediaPlayerEvent event carries the name of the event in the mediaPlayerEvent variable. Twitch is the only player whose events describe the broadcast rather than the visitor:

mediaPlayerEvent	Fires when
`online`	The channel goes live while the player is on the page.
`offline`	The channel stops broadcasting.

Neither carries a mediaPlayerEventParam.

Live streams report no progress

A live broadcast has no end, so the Twitch player reports no duration for one. Progress is measured as a share of the total length, and there is no total, so a live stream fires no gtm4wp.mediaPlaybackPercentage events at all. The state changes still work: you will see play and pause for a live viewer, just no milestones.

Recorded videos, the ones Twitch calls VODs, do report a duration, so milestones work normally for them.

What mediaData holds for a Twitch embed

Variable	Contents
`mediaData.id`	The video ID if the embed points at one, otherwise the channel name, otherwise the collection ID.
`mediaData.author`	The channel name. Twitch is one of only four players that report an author.
`mediaData.title`	The same value as the ID. The Embed API exposes no readable title.
`mediaData.url`	The Twitch address of the video or the channel. An embed that points only at a collection reports an empty URL.
`mediaData.duration`	The length in seconds, or 0 for a live stream.

The mediaType variable is twitch in every event.

Google Tag Manager built-in Video variables

Every Twitch media event also populates the built-in Video variables of Google Tag Manager, with Video Provider set to twitch. The section on built-in Video variables explains how to enable and use them. Video Title holds the ID, so use mediaData.author when you want the channel name in a report, and Video Visible is measured on the container the rebuilt player sits in.

Building a trigger in Google Tag Manager

To fire a tag when a visitor starts watching:

Create a Data Layer Variable named mediaPlayerState.
Create a Custom Event trigger whose event name is gtm4wp.mediaPlayerStateChange.
Add the condition mediaPlayerState equals play to the trigger.
Attach the trigger to your tag. To report which channel was watched, create a second Data Layer Variable named mediaData.author.

Limitations

Your iframe is replaced with a player the Twitch Embed API builds. Only the channel, video, collection, width and height are carried across, so any other attribute, class or style on the original embed is lost.
Live streams report no duration and therefore fire no progress milestones.
mediaData.title is the video ID or the channel name, not a readable title.
An embed that points only at a collection reports an empty mediaData.url.
There is no buffering state.
Progress is measured by asking the player for its position once a second while it plays.
There is no 100 percent milestone. See playback percentage milestones.
The tracker script loads on every page of your site when the option is on. The Twitch Embed API does not: it is fetched from embed.twitch.tv only on pages that actually contain a Twitch embed, so treat it like any other 3rd party script when you plan your consent setup for those pages.

The overview of media player tracking describes the events, data layer variables and playback milestones that every player shares. See also Dailymotion, the other player whose embed is rebuilt, and dynamically inserted players, which explains how a rebuilt embed is kept from being wired twice.