Event Tracking and Analytics with THEOplayer

Everyone knows the expression: “Knowledge is Power”. Having a large viewer base is good. Knowing how your viewer base interacts with your content is better.

With THEOplayer and its JavaScript API, you can gather this kind of information and help you improve the content you provide to your users as well as grow your viewer base and your business.

In this tutorial we’ll go over how to set up Event Tracking on your website with THEOplayer as well as show you a number of integrations that come pre-packaged with your THEOplayer library. That way you’ll be up and running with your favorite analytics platform and leveraging viewer data to improve your business processes in no time!

Table of contents

 

To help you get the most from your content, as well as integrate with the majority of analytics systems out there, THEOplayer follows the W3C standard for Media Events. This ensures any Event Tracking you do with THEOplayer is straight-forward and easy to hook into existing infrastructure.

A full list of events that are supported by THEOplayer can be found in our API.

Next to the events that THEOplayer dispatches, there are also different properties that are exposed by all the objects of the player. We will occasionally touch on some of these in this user guide, but for a full list of them you can go to the THEOplayer API.

On top of giving you a full box of tools to perform all the Event Tracking you could want, THEOplayer also comes with a few built in analytics hooks that allow you to integrate THEOplayer with the analytics platform of your choice.

Google Analytics

THEOplayer provides built-in configuration for Google Analytics. To let THEOplayer register event messages to your Google Analytics tracker requires just one quick setting in the configuration:

var configuration = {
    plugins : {
        googleAnalytics : true
    }
};

When the googleAnalytics plugin is set to ‘true’, THEOplayer will scan the web page it is on for Google Analytics trackers. All of these trackers will then receive the following event tracking messages:

  • ended
  • error
  • pause
  • play
  • playing
  • seeked
  • seeking
  • stalled
  • warning

Every time THEOplayer fires one of these events, the Google Analytics tracker will receive the following message:

  • hitType: 'event',
  • eventCategory: 'video',
  • eventAction: event type,
  • eventLabel: Source
  • eventValue: currentTime

Conviva

THEOplayer provides direct support and integration with the Conviva analytics platform, allowing you to provide a world-class experience to your viewers and reach all the tools to monitor and benchmark the QoE of your users.

Connecting THEOplayer to the Conviva platform requires you to add the following configuration parameters to THEOplayer:

var configuration = {
    conviva : {
        customerKey: "my-conviva-customer-key",
        gatewayUrl: "my-conviva-gateway-url",
        contentMetadata: {
            assetName: "my-conviva-asset-name",
            live: ‘true’ or ‘false’
        }
    }
};

Youbora by NicePeopleAtWork

Youbora is an end-to-end Business Intelligence and Analytics platform for your video solution. As the top layer of your video stack, THEOplayer will be the face of your video solution to your customer.

To help you get that value from your data, THEOplayer provides an easy integration with the Youbora platform:

???

Nielsen DTVR

DTVR (Digital Television Ratings) is a product of Nielsen that measures live TV viewing up to seven days of broadcasting without change in National ads. THEOplayer integrates smoothly with the Nielsen DTVR Web SDK to allow you to track this information in real-time.

All that is required is to provide the following parameters to THEOplayer and you’re good to go:

var configuration{
    nielsen : {
        sfcode: 'sfcode for collection location',
        apid: 'Nielsen Application ID',
        apn: 'player/site description',
        metadata : {
            channelName : 'name of the metadata channel'
        }
    }
};

Custom Events Tracking

Every company is unique and so are your needs. Therefore you might want to do analytics in a way that isn’t currently out there. Or you might simply prefer to rely on the things you’ve built yourself.

Either way, THEOplayer will make it possible for you to track the events from the player and run your custom JavaScript when specific events are fired. In the next segment we’ll show you some examples on how you can do this.

Step 1: The player setup

As usual we’ll need to instantiate THEOplayer on our web page:

<script>
    var theoplayer = window.theoplayer = window.theoplayer || {};
    theoplayer.configuration = theoplayer.configuration || {};
    theoplayer.configuration.skipAutoDetect = true;

    var player;

    theoplayer.onReady = function () {
        var video = document.getElementById("myVideo");
        player = theoplayer(video);
    }
</script>

Step 2: The custom function

Now that we have our player instance, we’ll write our custom function. In this function we’ll gather the data and properties we are looking to gather from THEOplayer.

We’ll also have to communicate with our analytics platform in this function. This way we’re sure that all this information reaches our analytics platform:

<script>
    function trackPlay() {
        var source = player.source,
            timestamp = Date.now();

        myAnalyticsTracker.track(source, timestamp);
    }
</script>

Step 3: Attaching the function

The final step to get our information sent to our analytics platform is done by hooking an EventListener to our THEOplayer instance. That way, when THEOplayer fires the event, the JavaScript engine of our viewer’s browser will run our custom function which sends the information to our platform.

<script>
    player.addEventListener('play', trackPlay);
</script>

Custom events tracking: Krux (Example 1)

Krux is a marketing hub which allows (custom) tracking. To add Krux tracking, you need to include the Krux tag.

<script class="kxct" data-id="[KRUX-ID]" data-timing="async" data-version="3.0" type="text/javascript">
    window.Krux||((Krux=function(){Krux.q.push(arguments)}).q=[]);
    (function(){
        var k=document.createElement('script');k.type='text/javascript';k.async=true;
        k.src=(location.protocol==='https:'?'https:':'http:')+'//cdn.krxd.net/controltag/[KRUX-ID].js';
        var s=document.getElementsByTagName('script')[0];s.parentNode.insertBefore(k,s);
    }());
</script>

If you want to track specific THEOplayer events, you use Krux() and forward them to Krux.

Krux([ns:[namespace]], [event_name], [event_id], [event_metadata]);
 namespace String  The namespace of your Krux account.
 event_name String The name of the event you want to track.
 event_id String  The identifier of the event.
 event_metadata Object The data object with metadata of the event you want to transfer. 

For example, to track a play event with Krux:

player.addEventListener('play', function() { 
Krux(
'ns:theoplayer',
'video_pause',
'5rge6432',
{
'video_src': player.src,
'video_current_time': player.currentTime
}
);
});

Custom events tracking: Tealium (Example 2)

Tealium is a universal tag manager, providing integration with Google Analytics, Facebook, and so on. To add Tealium tracking, you need to include the Tealium tag.

<script type="text/javascript">
    (function(a,b,c,d){
a='//tags.tiqcdn.com/utag/[ACCOUNT]/[PROFILE]/[ENV]/utag.js';
b=document;c='script';d=b.createElement(c);d.src=a;
d.type='text/java'+c;d.async=true;
a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)
})(); </script>

If you want to track specific THEOplayer events, you can use utag.link() to forward them to Tealium. The utag.link() method is intended for page interactions and other dynamic events.

utag.link([data_object], [callback], [uid_array]);
data_object Object, optional The data object containing the attributes associated with this specific tracking call.
callback Function, optional A function to be executed after the tracking call has completed.
uid_array Array, optional Only trigger a tracking call for the vendor tags specified by the UID's in this array.

For example, to track a pause event with Tealium:

player.addEventListener('pause', function() { 
utag.link({
"event_name" : "video_pause",
"video_id" : ["1ge545"],
"video_name" : ["Big Buck Bunny"],
"video_src" : [player.src]
});
});

That’s all there is to it. If you’re looking to get started with streaming video and want to be able to track your viewers’ experience, get started with THEOplayer TODAY!

If you need assistance in setting up your Event Tracking with THEOplayer, reach out to our support: here.