How to do a custom integration with an Analytics system

Introduction

Video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value.

What most video analytic systems have in common  is that their insights (partly) originate from video events:

  • play event: a user clicks the play button, or resumes playback after a pause
  • fullscreen event: a user goes fullscreen on their device
  • quality change event: the video quality switches from a lower resolution to a higher one
  • waiting event: the video is stalled and unable to continue playback for some time
  • ...

These systems gather raw data like the events above and convert it into understandable insights.

This guide will explain how to do a custom integration with an analytics system and will be useful in case THEOplayer isn't pre-integrated with the system, or you want to fully control which data gets sent over.

Google Analytics (GA) is used as an example, due to its widespread use for analytics in general.

Keep in mind that GA is not the only system out there. You can easily swap out the Google Analytics example for something like Nielsen or Youbora (Nice People At Work), or even your own analytics back-end.

We also provide pre-integrations for the following analytics systems:

A custom integration for the systems above is most likely not needed. We constantly validate our pre-integrations, ensuring you that they are up-to-standard and up-to-date.

In our 1.X player, we have a pre-integration for Youbora (Nice People At Work), Conviva, Google Analytics, Nielsen and more.

1. Prerequirements

There are two prerequirements in order to continue with this guide:

  1. You have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial here.
  2. You have some basic knowledge on how to use THEOplayer, and can navigate comfortable through the API to find relevant events.

2. Starting Template

This guide will not discuss how to set-up a basic template, and how to understand it. We dive in to the analytics code, which could be placed as mentioned in the code comment below.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
<title>THEOplayer 2.X: Getting Started</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href='/path/to/ui.css'> <!-- ads THEOplayer CSS -->
</head>
<body>

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

<script type='text/javascript' src='/path/to/THEOplayer.js'></script>
<!-- ads THEOplayer library -->

<script>

var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element, {
libraryLocation : '/path/to/your-theoplayer-folder/'
});

/** COMMENT: ANALYTICS CODE **/

player.source = {
sources : [{
src : '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
type : 'application/x-mpegurl'
}]
};

</script>

</body>
</html>

3. Integrating Google Analytics

Google Analytics (GA) requires you to load in the GA library and configure it through JavaScript.

<head>
...
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
             (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
         m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
 })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

 ga('create', 'UA-XXXXXXXX-XX', 'auto');
 ga('send', 'pageview');
...
</head>

Secondly, you want to set-up trackers, which can store data and send it to Google Analytics.

var tracker = {
    entries : [],
    send : function (entry) {
        this.entries.push(entry);
    }
};

if (!window.GoogleAnalyticsObject || !window[window.GoogleAnalyticsObject]) {
    // TODO: If code is set in configuration and no analytics initialised on page with said code -> initialise it
    // There is no Google Analytics initiated on the web page - do nothing.
    return;
}

ga(function() {
    var trackers = ga.getAll();
    var t = window[window.GoogleAnalyticsObject].getAll()[0];

    for (var i = 0; i < tracker.entries.length; i += 1) {
        t.send(tracker.entries[i]);
    }

    tracker = t;
});

The remaining part is to send relevant events to Google Analytics. The easiest method is to subscribe to a lot of THEOplayer events, and send them over through the tracker.

player.addEventListener(['durationchange', 'stalled', 'ended', 'seeking', 'seeked', 'waiting', 'playing', ' pause', 'volumechange'], function (event) {
    tracker.send({
        hitType: 'event',
        eventCategory: 'video',
        eventAction: event.type,
        eventLabel: player.src,
        eventValue: Math.floor(player.currentTime)
    });
});

Of course, you control the code, so you could send custom "made-up" events. A useful example would be the firstplay event, which would map to the first play event for a session.

var firstplay = true;
player.addEventListener('play', function (event) {
    if (firstplay) {
        tracker.send({
            hitType: 'event',
            eventCategory: 'video',
            eventAction: 'firstplay',
            eventLabel: player.src,
            eventValue: Math.floor(player.currentTime)
        });
        firstplay = false;
    }
    tracker.send({
        hitType: 'event',
        eventCategory: 'video',
        eventAction: event.type,
        eventLabel: player.src,
        eventValue: Math.floor(player.currentTime)
    });
});

Keep in mind that it would be wise to set firstplay to true again when you change the player's source.

Remember that not every event is accessible through the player property. For example, if you want to notify GA of a video quality change event, you have to subscribe to the correct video track.

player.videoTracks.addEventListener('addtrack', function(e0) {
    e0.track.addEventListener('activequalitychanged', function(e1) {
        tracker.send({
        hitType: 'event',
        eventCategory: 'video',
        eventAction: e1.type,
        eventLabel: player.src,
        eventValue: Math.floor(player.currentTime)
    });
});

4. Conclusion

A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the start of an ad, or a direction change event in 360/VR playback.

Extra resources:

  1. THEOplayer API
  2. THEOplayer Getting Started Guide
  3. Examples of using 2.X events