Data collection with pipe.js

The purpose of this tutorial is to show you how to add pipe.js, and use it in order to collect data depending on client informations.

How this works

The snippet we identify as loader is the small JavaScript below, which you will need to add to all your pages to start collecting data. The loader is designed to buffer the collected data without slowing down the browser when loading the page. First, the loader defines the _pipe function as a simple queue and stores the calls into a JavaScript array. Thus, it allows you to start pushing collect data even if the pipe library has not finished to load. Then, once loaded, the _pipe function is replaced by a callable object which will directly send the data to the collection APIs using the preferred method of the browser.

Also in order to track users and collect consistent data, two cookies are set by the collect server for a user. One of them never expires (cookie_id), thus it stays inside the browser and allows to uniquely identify the browser over time. The second (session_id) expires when closing the browser. Therefore, it can be used to identify uniquely the session of the user.

Most European countries require website providers to inform their visitors about Cookie usage on their website. Make sure you comply to legal regulations in place in your country before using the Pipe library on your webpages.


Prerequisites

To be able to complete this tutorial, you will need a site key provided by the EBU that matches your account informations. That site key can be created following this link (if you encounter a 403 Forbidden error, you may need to log in or create an account on EBU's platform). For the meaning of this tutorial, you can use zzebu00000000017 as site key.

Production site key

To be able to create the site key for production you will need access to https://ebu.io/peach. If you need an account, feel free to contact us so we can manage it with you.


How to integrate pipe.js lib

To start collecting data, include the loader in the header of the pages:

<script>

!function(){window.EBUPipeQName="_pipe","_pipe"in window||(window._pipe=function(){
window._pipe.q.push(arguments)},window._pipe.q=[]),window._pipe.startTime=(new Date).getTime();
var e=document.createElement("script");e.src="//d3kyk5bao1crtw.cloudfront.net/pipe-latest.min.js",
e.async=!0;var i=document.getElementsByTagName("script")[0];i.parentNode.insertBefore(e,i)}();

_pipe('register', 'zzebu00000000017');

_pipe('collect', 'pageview');

</script>

And you are all done ! (pretty much).

In more details, some points regarding the loader you should be aware of before starting :

  • the src="//d3kyk5bao1crtw.cloudfront.net/pipe-latest.min.js" is loading the latest version of pipe.js. In some cases you would rather want to fix this version. You can then simply use something like src="//d3kyk5bao1crtw.cloudfront.net/pipe-0.6.3.min.js" instead.
  • the method _pipe('register', 'zzebu00000000017'); that registers pipe regarding your domain name and enable it. About that, you will not be able to collect anything until the register method will be completed. Although, all collect methods call will be queued, and processed at the moment pipe will be enabled and registered.
  • _pipe('collect', 'pageview'); is a basic collect call. The former parameter will be considered as the event, the latter as action. The third argument is either a string describing the content's id or an object with additional variables to be collected.

Info

You can use our hosted library but define your own collection servers or your local server for testing purposes. You need to set it before registration.

Two ways of doing it : _pipe('setEndpoint', 'localhost:8080'); or _pipe('setEndpoint', ['localhost:8080','localhost:8081']);

You need to use a local server (MAMP, Intellij built in server etc.) to run the example. Else you may experience some issues with links to external files.

Start sending data to collect APIs

Now that our pipe.js is registered and ready to use, let's try to add a simple button to start collecting data.

First create a simple button element

<input id="button" type="button" value="Test" onclick="testSend()"/>

Now simply create the function that will send some data to your newly registered pipe.js

function testSend() {
  _pipe('collect', 'test_click');
}

If you open your browser console and check the network tab, you should be able to see a POST request sent to POST "http://pipe-collect.ebu.io/v1/collect?s=zzebu00000000017&e=test_click" with success and the request payload with all collected data.

In case you have a 405 HTTP error on OPTIONS request, it is most likely because the site key is not registered correctly. Check here that the site key appears and is enabled

Collect data from a player

For the purpose of this tutorial we will demonstrate how to get data from basic html5 player, and send them to pipe collect API. Of course, you will most likely use your own player with other constraints and needs, but this is really just to have a quick and working overview of the process.

First thing to do, create a basic html document and add your video element

 <video id="video" controls="true">
    <source src="http://techslides.com/demos/sample-videos/small.mp4">
 </video>

Then, make sure you properly initialized the library as explained in the section above.

Now, let's start capturing events from the player. We got a video element in the DOM and pipe.js registered. So we will simply add the event listeners for the video we want to collect informations from.

var player = document.getElementById("video");

player.addEventListener("play", function (evt) {
    playing(evt);
});

player.addEventListener("pause", function (evt) {
    paused(evt);
});

function playing(evt) {
    console.log("play", evt);

    var currentPlayer = evt.target;
    //record the event fired on the player
    var event = evt.type ? evt.type : 'playing';
    //record audio/video/other type
    var type = currentPlayer.type ? currentPlayer.type : 'video';
    //get all data you can collect from your video to send them to collect
    var data = {
        id: currentPlayer.id,
        title: currentPlayer.title,
        duration: currentPlayer.duration.toFixed(1),
        type: type,
        recommendationid: currentPlayer.getAttribute('data-recommendation-id')
    };
    _pipe("collect", event, data);
}

function paused(evt) {
    console.log("pause", evt);
}

You noticed the recommendationid attributes. It is important so we will be able to collect its value on each player event. You can pass it the way you want, but it is critical to always send the recommendationid when you collect events from a player if you want an accurate recommendation system. In this example, the parameter data-recommendation-idwill not be found so it will basically be undefined, but in the next part of this tutorial we will need to grab this value and use it.

As you can see, it is nothing more than basic javascript. Whenever a client will play/pause on the video, the corresponding event will be fired and we will then get the right, formatted data we watn to collect with pipe.


Do not forget

The first argument of `_pipe method is the collect command, the second is the action type and the third is either a string describing the content's id or an object with additional variables to be collected. You can choose freely the name of the events, however you must know that each choosen name will result in one distinct analytics set. We recommended to use the following action names :

  • pageview
  • playing
  • paused

More recommendations about how to name your actions: Metrics


Additional Documentation

Some documents to know more about pipe :

  • pipe.js documentation: More details on available informations, options, and methods using pipe.js.
  • Metrics: Proposition to standardize and set the best practices in terms of media consumption and data collection.

Final notes

If you followed this tutorial entirely you should now be able to collect with pipe.js, following our best pratices. You noticed anything missing, wrong or not working? Do not hesitate to contact us and we will be pleased to answer your request.

The code for this tutorial is available in the repository. Also you can access a slightly enhanced version of the page directly here.