Tracking HTML5 Video / Audio Elements

One of the most popular features in web analytics involves tracking how people interact with videos and audio on websites. Whether featuring promotional videos, educational content, or podcasts, understanding audience engagement proves invaluable. Quality tracking reveals interaction patterns such as play frequency, viewing/listening duration, and abandonment points -- information that helps optimize content and user experience.

In the Flash era, tracking media interactions presented significant challenges. Today, HTML Media <video> and <audio> tags simplify this process considerably. These native tags include built-in capabilities for monitoring user actions: play initiation, pause events, and volume changes. This evolution has made media engagement tracking substantially more straightforward for website operators.

Library Overview

The Analytics Debugger team released an open-source HTML Media Elements Tracking Library available in AMD, UMD, IIFE, and ESM formats for broad compatibility.

This plug-and-play library handles implementation details automatically. Current features include:

• GTM DataLayer Support
• Tealium Support
• Automatic new videos/audio detection
• DOM Mutations detection (for dynamically injected videos)
• Data elements support for passing video metadata
• Progress tracking
• Start, Pause, Mute, Unmute, Seek, Complete and Error events
• GTM Template

Supported Events

The library tracks these interaction events:

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

DOM Mutation Listeners

Video tracking complications often arise when content loads dynamically, creating race conditions. The library features a built-in DOM Mutation listener that continuously monitors DOM changes, automatically attaching tracking to newly inserted videos. This functionality streamlines the tracking process significantly. Users can disable this feature during initialization by setting observe: false.

Data Model

The library captures comprehensive video interaction data with these key fields:

Setting Up

Initialize tracking by specifying desired events and data transmission method:

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

<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>

For debugging, use debug as the TMS setting to print information to the browser console. For full Google Tag Manager integration, utilize "gtm" to ensure data compliance with GTM standards. Leverage "tealium" to perform utag.link calls for Tealium framework tracking.

Using a Custom Video Title

Most implementations track the ID or video file name by default. However, this library allows customization through data attributes, enabling precise control over how video names are recorded.

If a data-html-media-element-title attribute is provided, the video title will use that custom value. Without this attribute, the library defaults to the current video file name.

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

The library enables passing any desired metadata using the format data-html-media-element-{PARAMNAME}:

<video width="400"
  controls
  data-html-media-element-param-band="Neil Zaja"
  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 includes metadata details under the videoData key, simplifying the process of passing author information, years, categories, or other desired information. This data maps easily to events for comprehensive tracking.

Example output:

{
    element: video
    elementClasses: ""
    elementId: "vbst4f9ed29"
    elementTarget: video
    elementUrl: "https://local.dev/demo/mp3.html"
    event: "video"
    videoCurrentTime: 2
    videoData:
        band: "Neil Zaja"
        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

For streamlined implementation, Analytics Debugger provides a ready-to-use Community Template for Google Tag Manager available at the GTM Template Gallery.

Source code resides in the Github Repository.

Direct CDN access via jsdelivr.

Notes

While this library tracks many player types, iframe-based video providers may offer alternative APIs. Investigation of provider-specific tracking options may be necessary. For difficulties or assistance, don't hesitate to reach out to us.