Vimeo video tracking in Google Tag Manager

Google Tag Manager for WordPress reports how your visitors watch the Vimeo videos embedded on your site. Starting playback, pausing, seeking, buffering, changing the quality or the playback rate, going full screen and switching to Picture in Picture all become data layer events that you can use as triggers in Google Tag Manager.

This page describes GTM4WP 2.0.0 and newer. Events introduced by that release are marked New in 2.0.0. Where the legacy 1.x versions of the plugin behaved differently, the older behavior is marked with a bold GTM4WP 1.x: lead-in.

Vimeo tracking is stable, so the option carries no badge in the plugin settings.

GTM4WP 1.x: the option was marked experimental.

Turning Vimeo tracking on

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

Which embeds are detected

The tracker wires every iframe whose src contains vimeo.com. That covers the embed code you copy from Vimeo, the Vimeo block of the block editor and a plain Vimeo URL pasted on its own line, because WordPress turns all of them into the same player iframe.

The video ID and the reported URL are read from the embed address with the query string and any fragment removed. Both halves matter: a #t=30 start time you added by hand, or the fragment WordPress appends to embeds of its own accord, would otherwise become part of the video ID and of every URL you report.

Tracking depends on the official Vimeo Player SDK, which is only requested once the tracker has actually found a Vimeo embed on the page, so a page without one never contacts Vimeo. 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. A video 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	Availability
`play`	Playback has actually started, after any initial buffering.
`pause`	The visitor pauses the video.
`ended`	The video reaches its end.
`seeked`	The visitor jumps to another position.
`buffering`	The player starts buffering.	New in 2.0.0
`bufferend`	The player finishes buffering.	New in 2.0.0

GTM4WP 1.x: the play state came from the play event of the Vimeo SDK, which fires as soon as playback is requested. It now comes from the playing event, which fires once the video really starts. A video that buffers before it starts therefore reports buffering first and play afterwards. Expect a trigger that counts plays to report slightly fewer, and more accurate, starts after the upgrade.

Player events

The gtm4wp.mediaPlayerEvent event carries the name of the event in the mediaPlayerEvent variable and the accompanying value in mediaPlayerEventParam. Vimeo reports the widest set of these of all the supported players:

mediaPlayerEvent	mediaPlayerEventParam	Availability
`texttrackchange`	The text track the player switched to.
`volumechange`	The new volume.
`error`	The error reported by the player.
`playbackratechange`	The new playback rate.	New in 2.0.0
`qualitychange`	The new quality.	New in 2.0.0
`fullscreenchange`	`true` when the player entered full screen, `false` when it left.	New in 2.0.0
`enterpictureinpicture`	`true`	New in 2.0.0
`leavepictureinpicture`	`true`	New in 2.0.0

The plugin also pushes an error event when a call to the Vimeo SDK fails, for example when it cannot read the title or the duration of a video. In that case mediaPlayerEventParam holds the error returned by the SDK, and mediaData.title can read Unknown title.

What mediaData holds for a Vimeo video

Variable	Contents
`mediaData.id`	The numeric Vimeo ID, taken from the last part of the embed address.
`mediaData.author`	Always empty. The Vimeo Player SDK exposes no owner or channel name.
`mediaData.title`	The title of the video, read from the SDK when the player becomes ready.
`mediaData.url`	The embed address without its query string or fragment, for example `https://player.vimeo.com/video/76979871`.
`mediaData.duration`	The length of the video in seconds.

The mediaType variable is vimeo in every event.

Google Tag Manager built-in Video variables

New in 2.0.0. Every Vimeo media event also populates the built-in Video variables of Google Tag Manager, with Video Provider set to vimeo. The section on built-in Video variables explains how to enable and use them.

One value is worth knowing about in advance. The bufferend state has no counterpart in Google Tag Manager, so Video Status is empty on that event. Read mediaPlayerState instead when you need to tell the start of buffering apart from its end.

Video Visible is measured on the embed iframe, so it reports whether that video was on screen when the event fired.

Building a trigger in Google Tag Manager

To fire a tag when a visitor starts a Vimeo 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 send the title of the video along with it, create a second Data Layer Variable named mediaData.title.

Use ended in place of play to measure a video that was watched to the end. To measure progress, build the trigger on gtm4wp.mediaPlaybackPercentage and add a condition on mediaPercentage instead.

Limitations

The name of the uploader is never reported, because the Vimeo Player SDK does not expose it. Build a lookup table in Google Tag Manager on mediaData.id if you need it in your reports.
The title and the duration come from two asynchronous calls to the SDK, so gtm4wp.mediaPlayerReady fires a moment after the player appears rather than at once.
When a call to the SDK fails, the plugin pushes an error event for that video and no ready event.
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 Vimeo Player SDK does not: it is fetched from player.vimeo.com only on pages that actually contain a Vimeo 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 YouTube, whose option is deprecated in favor of Google Tag Manager’s own trigger, and dynamically inserted players if your videos open in a popup or a lightbox.