Tracking HTML5 Video / Audio Elements

One of the most popular features in web analytics is tracking how people interact with videos and audio on your websites. Whether you have promotional videos, educational content, or podcasts, knowing how your audience engages with them is very helpful. Good tracking can show you important details like how often videos or audio are played, how long people watch or listen, and when they stop. This information helps you improve your content and make the user experience better.

Back in the days when most media players relied on Adobe Flash, tracking user interactions with videos and audio was a significant challenge. However, things have improved greatly. Today, many providers use HTML Media <video> and <audio> tags, which simplify the process. These HTML tags come with built-in capabilities that make it easier to monitor user actions, like when a video or audio starts playing, pauses, or changes volume. This shift has made it much more straightforward to track and analyze media usage on your websites.

That’s why we released some years ago our own “HTML Media Elements Tracking Library” . The library is provided for free in the AMD, UMD, IIFE and ESM formats so it can be used almost anywhere.

We build this library to be a plug & play, so poeple doesn’t need to worry about the details. Current features are:

Features

• GTM DataLayer Suppor
• Tealium Support
• Automatic new videos/audio detection
• Dom Mutations detection ( for after load injected Videos )
• Data elements support to pass back data for the current video
• Progress tracking
• Start, Pause, Mute, Unmute, Seek, Complete and Error events
• GTM Template

Supported Events

•  start
•  pause
•  mute
•  unmute
•  progress ( % of video played )
•  seek
•  complete ( equals to 100% progress )
•  errors

Dom Mutation Listeners

One of the biggest headaches in video tracking arises when videos are dynamically injected into the page, leading to race conditions and other tracking challenges. However, the library features a built-in DOM Mutation listener. It continuously monitors DOM changes, automatically adding tracking whenever a video is attached to the DOM. This functionality significantly simplifies the tracking process. You can disable this feature while initializating the library ( observe: false )

Data Model

Setting up

Here’s how you can initialize the tracking: simply specify the event you wish to monitor and how you want to transmit the data to our end.

Absolutely, it’s as straightforward as that, and all interactions with your videos will seamlessly flow into your dataLayer.

<script src="https://cdn.jsdelivr.net/npm/@thyngster/html-media-elements@latest/dist/htmlMediaElementsTracker.min.js">

<script>
    window._htmlMediaElementsTracker.init({
        tms: 'debug',
        datalayerVariableNames: ['auto'],
        debug: true,
        observe: true,
        data_elements: true,        
        start: true,
        play: true,
        pause: true,
        mute: true,
        unmute: true,
        complete: true,
        seek: true,
        progress: true,
        error: true,
        progress_tracking_method: 'percentages',
        progress_percentages: [1,2,3,4,5,6,7,8,9,10],
        progress_thresholds: [],        
    });   
</script>

To assist with debugging, we can use debug as TMS to print information to the browser console. For full Google Tag Manager (GTM) integration, we can utilize the "gtm" setting to ensure the data is compliant with GTM standards. Additionally, we can leverage "telium" to perform utag.link calls, enabling tracking within the Tealium framework.

Using a custom Video Title

Most of the time, we’ll track the ID or the video file name by default. However, this library allows us to customize the tracking by providing data attributes. This means you can specify exactly how you want the video name to be recorded, giving you more control over your tracking and reporting.

If a “data-html-media-element-title” attribute is provided, the video title will be reported using that custom value, such as “Demo Video version 1.” If no data attribute is specified, the library will default to using the current video file name for tracking.

<video src="" data-html-media-element-title="Demo Video version 1">

In addition to that, the library enables you to pass any metadata you desire for the tracking. This can be achieved using the format: data-html-media-element-{{PARAMNAME}}, as demonstrated in the following code snippet:

<video width="400" 
controls 
data-html-media-element-param-band="Neil Zaza"
data-html-media-element-param-song-name="I'm Alright"
data-html-media-element-param-category="Music"
data-html-media-element-title="video test">
    <source src="mov_bbb.mp4" type="video/mp4">
    <source src="mov_bbb.ogg" type="video/ogg">
    Your browser does not support HTML video.
</video>

The library will handle the inclusion of metadata details with each push, neatly organizing them under the “videoData” key. This simplifies the process of passing video details such as authors, years, categories, or any other desired information. We can then easily map this data to our events for comprehensive tracking.

{
     element:  video
     elementClasses:  ""
     elementId:  "vbst4f9ed29"
     elementTarget:  video
     elementUrl:  "https://local.dev/demo/mp3.html"
     event:  "video"
     videoCurrentTime:  2
     videoData:
    	 band:  "Neil Zaza"
    	 category:  "Music"
    	 songname:  "I'm Alright"
     videoDuration:  361
     videoElapsedTime:  2
     videoIsMuted:  false
     videoLoop:  false
     videoNetworkState:  1
     videoPercent:  0
     videoPlaybackRate:  1
     videoProvider:  "html5"
     videoStatus:  "pause"
     videoTitle:  "video test"
     videoUrl:  "mov_bbb.mp4"
     videoVisible:  true
     videoVolume:  1
 }      

GTM Template

If you want to go in the easyh way we provide a full ready-to-use Community Template for Google Tag Manager, that you can find here:

https://tagmanager.google.com/gallery/#/owners/analytics-debugger/templates/gtm-html-media-elements-tracker

And you can also find the source code on the following Github Repository:

https://github.com/analytics-debugger/html-media-elements-tracking-library

or direcly use it from the jsdelivr CDN:

https://www.jsdelivr.com/package/npm/@analytics-debugger/html-media-elements

Notes

While this library should be able to track many of the players around, if your current video provider uses an iframe, they may offer alternative APIs to track the videos. In this case, you’ll need to investigate the tracking options they provide. If you encounter any difficulties or need assistance, feel free to reach out to us for help. We’re here to support you!