Skip to content

Data collection with peach-collector.js

The purpose of this document is to show you how to add peach-collector.js and use it in order to collect data depending on client informations.

How it works

First we have to load the peach-collector.js main script, located here.

This step provides the _pc javascript object that has all the needed functions for initialisation and event collection on it.

Also in order to track users and collect consistent data, four 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. The third one (tracking) stores the informtion about allowed tracking. This will override a clients browser "do not track" setting. The fourth cookie (last_recorded) does recording of the last activitys timestamps to re-create sessions if neccessary.

Most European countries require website providers to ask their visitors about Cookie usage, any kind of tracking or data collection on their website. Make sure you comply to legal regulations in place in your country before using the peach-collect 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. For the meaning of this tutorial, you can use zzebu00000000017 as site key, or get one from the PEACH core team.

Production site key

To be able to run in production you must have your own site key. Please contact us!


Integrate PeachCollector

You have to do the initialisation/setup calls, available as a file here.

(function (j, c) {
  var s = function (o) {
    var t = document.createElement('script');
    for (var p in o) {t[p] = o[p];};
    return t;
  };
  var p = s({src: j, defer: true, async: true, onload: c});
  var i = document.getElementsByTagName('script')[0];
  i.parentNode.insertBefore(p, i);
})('//peach-static.ebu.io/peach-collector.min.js', PeachCollectorLoaded);

function PeachCollectorLoaded() {
  var _pc = window._pc = new PeachCollector(window);
  _pc.init('my_site_key', 'my_app_id')
    .enableTracking()
    .sendPageViewEvent();
}

The loader creates a <script> tag which leads to loading the library itself and initialises the library. You'll have to call _pc.enableTracking() explicitly after init() to see data being sent! You'll get a site_key from us at EBU PEACH team, the app_id can be chosen freely.

Enabling the tracking

Call enableTracking() when you've asked your user for consent and peach-collector is allowed to collect data. This overrides any "do not track" settings, so be cautious with it. Any event triggered before you enable the tracking will be ignored and not sent.

Listen to sent data

For testing purpose, you can listen to the events that are sent by using the setSendEventCallback() function. Pass in a function, params are error, response and a payload. For example, _pc.setSendEventCallback(function(err,response,payload) { // some magic happens }; );

Defining endpoints

You can use our hosted library but define your own collection servers or your local server, as additional receivers or for debugging. See the section about advanced setup.


Sending events

Now that our peach-collector.js is registered and ready to use, you can send an event:

_pc.sendPageViewEvent();

If you open your browser console and check the network tab, you should be able to see a POST request sent to http://pipe-collect.ebu.io/v3/collect?s=<your site key>' with success and the request payload with all collected data.

In case you have a 40x HTTP error on OPTIONS request, it is most likely because the site key is not registered correctly. Make sure it is enabled and correctly initialized.

Create a context

A context is sometimes needed to understand an event (from a data science point of view). For example, we use it to track the source of a media. When you want to track performance of algorithms, it is very important to understand when media is watched after being recommended, and when it is not.

PeachCollector provides different functions to create contexts. Those context can then be used when sending an event.

// describe the component in which the event happened
var component = _pc.EventContextComponent(type, name, version);

// create any kind of context
var context = _pc.pageViewContext(referrer, recommendation_id);
var context = _pc.readMoreContext(source, component);
var context = _pc.mediaContext(id, type, referrer, page_uri, source, component);
var context = _pc.recommendationContext(items, item_id, hit_index, referrer, page_uri, source, component);

Defining properties

The props object provides details about an event (essentially used for media events). Setters are provided for all known fields (see Event Properties).

var props = _pc.EventProps().setPlaybackPosition(0);

Sending an event

For documentation of the possible events that are available, please see the events documentation.

var context = _pc.mediaContext('reco0001', 'recommendation', window.document.referrer, window.location.href);
var metadata = {'title' : 'My article'};  
_pc.sendArticleStartEvent('article10234', context, metadata);

Collect data from a player

To properly track media related events, you can set up event listeners on media objects:

var video_sample = document.querySelector('#video-sample');

video_sample.onplay = function (evt) {
  var media_element = evt.target;
  _pc.sendMediaPlayEvent(media_element);
}

Shorthand for tracking on media elements

You can without having to set up listeners add tracking to a specific media element. The tracking will by default then set up listeners for you. The default listeners will send events on play, pause and end events. But it's configurable to listen to all events that a media element produces.

var video_sample = document.querySelector('#video-sample');
var extended_event_config = { 
  media_heartbeat: {heartbeat_interval: 5}, // event_name, event_configuration or true
  media_seek: true
};
var context = {} || null;
var props = {} || null;
var metadata = {} || null;
_pc.trackMediaEvents(video_sample, 'my_id', context, props, metadata, extended_event_config);

Info

You can see this in action in the demo page.

Advanced setup

Multiple endpoints

You can make peach-collector send to not only one event receiver ("collect" endpoint), by default the EBU PEACH collect, but can use own and custom receivers. Instead of setting the site_key like above, first you have to define the endpoints as an array of objects like here:

function PeachCollectorLoaded() {
  var _pc = window._pc = new PeachCollector(window);
  var endpoints = [
    {
      sitekey: 'zzebu00000000017'
      // this is the default endpoint at EBU PEACH when no URL is given
      // but you'll always need your sitekey for it!
    },
    {
      url: 'http://collector.my-broadcaster.org/receiver'
      // this is a custom endpoint, a sitekey is probably not needed
    }
  ];
  _pc.init(endpoints, 'my_app_id')
    .sendPageViewEvent();
}

Now events will be dispatched to two collectors. There is no custom event format, so the custom endpoint exactly receives the same events as the EBU PEACH receiver. Notice how the site_key parameter, a string value, gets replaced by an array! In case you'd like to change endpoints after calling init() you can pass the endpoints to _pc.setCollectEndpoints() also.

Filtered events

You can set a list of events you want to receive on a given endpoint. This comes handy if you define a custom endpoint, but only for page_view events, for example. A valid setup could look like:

function PeachCollectorLoaded() {
  var _pc = window._pc = new PeachCollector(window);
  var endpoints = [
    {
      sitekey: 'zzebu00000000017'
      // again, the default, without event filter
    },
    {
      url: 'http://collector.my-broadcaster.org/receiver',
      filter: ['page_view']
    }
  ];
  _pc.init(endpoints, 'my_app_id')
    .sendPageViewEvent();
}

The filter is an array of whitelisted event types. This setup will send only page_view events to the custom endpoint, but everything to the default one.

Payload functions

For changing, enriching or reducing the event payloads you can use a payload_func. The events payload will be handed into and replaced by what you return from this function. For example:

function PeachCollectorLoaded() {
  var _pc = window._pc = new PeachCollector(window);
  var endpoints = [
    {
      sitekey: 'zzebu00000000017'
      // again, the default, without extra functions
    },
    {
      url: 'http://collector.my-broadcaster.org/receiver',
      payload_func: function (payload) { payload.event.foo = 'bar'; return payload; }
    }
  ];
  _pc.init(endpoints, 'my_app_id')
    .sendPageViewEvent();
}

Here you would add the foo key to the event payload with value bar. Again, this is only valid for the endpoint it's defined in.

Overview:

Parameter Name Value Explaination
url string URL to send to. Use ${sitekey} to insert sitekey value
sitekey string Mandatory for EBU PEACH collect endpoints.
filter array of strings Sets the event types to send to this endpoint
payload_func function Function to apply to the payload. Make sure to return it.

Data Collected

By using peach-collect.js, you get more data about the client automatically. This is a sample of what we receive with the code above :

{

    peach_schema_version: "1.0.3",
    peach_implementation_version: "peach-collector-js",
    site_key: "my_site_key",
    session_start_timestamp: 1582567123913,
    sent_timestamp: 1582569351215,
    collect_timestamp: 1582569351215,
    user_id: "anonymous",
    events: [
        {
            type: "page_view",
            id: "http://localhost:3000/",
            event_timestamp: 1582569351215,
            context: {
                page_uri: "http://localhost:3000/",
                referrer: ""
            }
        }
    ],
    client: {
        id: "2c0e4a10-cf43-396e-f1d5-596dbe99340e",
        app_id: "my_app_id",
        type: "web",
        name: "Mozilla/5.0 (X11; Linux x86_64; rv:73.0) Gecko/20100101 Firefox/73.0",
        version: "5.0 (X11)",
        device: {
            type: "Mozilla/5.0 (X11; Linux x86_64; rv:73.0) Gecko/20100101 Firefox/73.0",
            vendor: "",
            model: "Linux x86_64",
            language: "en",
            timezone: -1,
            screen_size: "1920pxx365.833px"
        },
        os: {
            name: "Linux x86_64",
            version: "5.0 (X11)"
        }
    }

}

Additional Documentation

Some documents to know more about Peach Collector :


Final notes

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