How to track embedded media players (YouTube, Vimeo, SoundCloud)

Introduction

Starting from v1.1 of this WordPress plugin you can easily track some popular media players embedded into your website. And not just that: remember, Google Tag Manager is not just about collecting data using Google Analytics! Lets imagine you can create a remarketing list on Facebook which collects views of your videos on your website. Fascinating, isn’t it?

The main goal while creating this feature was to create unified dataLayer variables and events among all currently supported media players:

• YouTube
• Vimeo
• Soundcloud

This was hard since besides some common events there are many different kind of events which are available in one media player but not in another. We created this article to make things clear and to provide a detailed documentation about how the plugin works with this feature.

Please remember: this is an experimental feature which means it can still have negative side effect on your site and also names of data layer variables and events can change in upcoming versions of the plugin.

Data Layer variables for all events

The following dataLayer variables are available in all implemented data layer events so that you can track details about the currently played media:

{
  'mediaType': 'youtube',
  'mediaData': {
    'id': '123abc456',
    'author': 'The Great Content Creator',
    'title': 'The Great Content of the Author',
    'url': 'https://youtube.com/watch/123abc456',
    'duration': 154
  },
  'mediaCurrentTime': 0
}

Lets explain what you can enter into the ‘Data Layer variable name’ field in the Google Tag Manager UI while you try to read the data layer and what you can expect to see when you are using this variable:

• mediaType: what kind of media is being played. Possible values are: youtube, vimeo, soundcloud
• mediaData.id: ID of the media in the database of the player’s website
• mediaData.author: due to limitations of the currently supported players, this data layer variable is only available if the currently played media is a SoundCloud file and contains the author of the sound
• mediaData.title: the title of the currently played media as seen on the website of the player
• mediaData.url: public URL of the played media
• mediaData.duration: duration of the played media in seconds
• mediaCurrentTime: the current position of the player in seconds

So if you need any of the above data you just have to create a new Data Layer Variable on the GTM UI and add the variables names in bold.

GTM events

There are several events that you can use to fire triggers in your Google Tag Manager setup. Many of them are common between media players so that you can create only a few tags to track any kind of players:

• gtm4wp.mediaApiReady: this is currently only fired for YouTube videos. It tells you that the YouTube API has been loaded and all features are now available on the page. I do not think there are many use cases here but who knows 🙂 This is the only event where only the mediaType data layer variable is available without details about the embedded YouTube video since at this stage we only know that the YouTube API is ready to start working in general and not connected to any video
• gtm4wp.mediaPlayerReady: this event is being called when a media player finished loading and is ready to interact with the user. This also means that this event is called for each embedded media on the page which can cause several or maybe a lot of GTM events thus be careful if you attach any tag to this event
• gtm4wp.mediaPlayerStateChange: this event is being called whenever the player starts to play the content, or the play state changes to buffering, ended, paused and so on. The current state of the player can be accessed using the mediaPlayerState data layer variable. The value of the mediaPlayerState data layer variable has been unified during development so that different values of media players (like ‘play’ or ‘playing’ or ‘started’) can be referred with one value (like ‘play’). Unified player state values are: play, pause, ended. You may also see additional player states to come up with YouTube: buffering, cued or with SoundCloud: seeked
• gtm4wp.mediaPlayerEvent: this is the common form of reacting to different events of different media players. YouTube for example can tell you whenever the quality of the played video changed where SoundCloud can tell you when the user clicks on a Buy button inside the player. If the event has any additional parameters, you can access them using the mediaPlayerEventParam data layer variable. The name of the event can be read using the mediaPlayerEvent data layer variable. Here is a list of currently supported event names:
  • playback-rate-change: fired by the YouTube API when the playback rate changes. The mediaPlayerEventParam will contain a number that represents the new rate.
  • error: fired by the YouTube API and the SoundCloud API. For the YouTube API mediaPlayerEventParam will contain an error code, for SoundCloud this is a general event without reporting the error message itself.
  • api-change: fired by the YouTube API to indicate that the player has loaded (or unloaded) a module with exposed API methods
  • click-download: fired by the SoundCloud API when the user clicks on the download button inside the player
  • click-buy: fired by the SoundCloud API when the user clicks on the Buy button inside the player
  • open-share-panel: fired by the SoundCloud API when the user opens the share panel inside the player
• gtm4wp.mediaPlaybackPercentage: if you need to track how much time the user has been played, use this data layer event. The plugin reports usage in every 10% of the duration which is currently a fixed number but there are plans to give You more control over this as well. Access the percentage using the mediaPercentage data layer variable.