Cloudflare Stream video tracking in Google Tag Manager

New in 2.0.0. Google Tag Manager for WordPress reports how your visitors watch the Cloudflare Stream videos embedded on your site. Starting, pausing, seeking, buffering and finishing become data layer events that you can use as triggers in Google Tag Manager.

This page describes GTM4WP 2.0.0 and newer. Cloudflare Stream 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. Cloudflare Stream is infrastructure rather than a media site, so it reports the mechanics of playback well and tells you very little about the video itself.

Turning Cloudflare Stream tracking on

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

Which embeds are detected

The tracker wires every iframe whose src contains cloudflarestream.com or videodelivery.net. Both hosts serve the same player, and which one you see depends on how the embed code was generated.

The video is identified by its UID, taken from the last part of the embed address. An address that ends in /iframe has the UID in the part before it, and the plugin handles that form as well. The address is read with its query string and any fragment removed first, which matters here more than it sounds: WordPress renders a Stream embed with a fragment on the end, and reading the last segment without cutting that off first would report every video as iframe# rather than as itself.

Tracking depends on the Cloudflare Stream Player SDK, which is only requested once the tracker has actually found a Stream embed on the page, so a page without one never contacts Cloudflare. The tracker also checks that the SDK is present before it wires each iframe, so a consent manager, an ad blocker or a network error that keeps it from loading leaves the video unmeasured rather than throwing an error on your page.

A video 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.

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 video.
`ended`	The video reaches its end.
`seeked`	The visitor jumps to another position.
`buffering`	Playback stops to wait for more data.

The Cloudflare Stream player follows the same design as the browser’s own media player, so these states behave much like the ones on the HTML5 video and audio page.

Player events

The gtm4wp.mediaPlayerEvent event carries the name of the event in the mediaPlayerEvent variable and the accompanying value in mediaPlayerEventParam.

mediaPlayerEvent	mediaPlayerEventParam
`ratechange`	The new playback rate.
`volumechange`	The new volume.
`error`	The error reported by the player.

What mediaData holds for a Cloudflare Stream video

Variable	Contents
`mediaData.id`	The Cloudflare Stream UID of the video.
`mediaData.author`	Always empty. The player exposes no owner.
`mediaData.title`	The title on the embed if it carries one, otherwise the UID. See below.
`mediaData.url`	The embed address without its query string or fragment.
`mediaData.duration`	The length of the video in seconds.

The mediaType variable is cloudflarestream in every event.

Whether you get a real title

The Stream Player SDK reports no title of its own, so the plugin reads the title attribute of the embed on your page instead. Whether one is there depends on how the video got onto the page.

A video WordPress embedded for you from a pasted link usually has one, because WordPress fills that attribute in from what the provider returned. The embed code you copy and paste out of the Cloudflare dashboard does not carry one, so those videos report the UID.

A Stream UID is a long string of letters and numbers, so a report built on it is unreadable without help. You can add a title attribute to your embeds by hand, keep a lookup table in Google Tag Manager mapping each UID to a name, or store the mapping in your reporting tool. Since you upload these videos yourself, you have the list of UIDs to hand, which makes this easier here than for the players whose IDs belong to somebody else.

Google Tag Manager built-in Video variables

Every Cloudflare Stream media event also populates the built-in Video variables of Google Tag Manager, with Video Provider set to cloudflarestream. The section on built-in Video variables explains how to enable and use them. Video Title holds whatever the title resolved to, and Video Visible is measured on the embed iframe.

Building a trigger in Google Tag Manager

To fire a tag when a visitor starts a Cloudflare Stream video:

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 identify the video, create a second Data Layer Variable named mediaData.id and, if you built one, run it through your lookup table.

Limitations

mediaData.author is always empty, and the title is only as good as the title attribute on your embed. Without one it is the Stream UID.
There is no 100 percent milestone. Measure a full watch with the ended state, as described under playback percentage milestones.
The tracker script loads on every page of your site when the option is on. The Stream Player SDK does not: it is fetched from embed.cloudflarestream.com only on pages that actually contain a Stream 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 VideoPress and HTML5 video and audio, the other two ways to measure video you host yourself.