@bbc/newslabs-helper-analytics

A simple helper to simplify pulling analytics into our projects without having to write boilerplate everytime

It is implemented using ES5 to be compatible with IE11 that has yet to adopt ES6

It is implemented in a function style

It mainly acts as a wrapper for Echo that makes it easier to calibrate: Echo Docs

Setup

npm i @bbc/newslabs-helper-analytics

Usage

Importing this package provies a single function that accepts an options object to calibrate Echo as needed for any given project

The helper must be instantiated with a string designating the name of your app or project

import analytics from '@bbc/newslabs-helper-analytics';

const options = {
  destination: 'NEWS_PS',
  labels: {
      name: 'newslabs.example.page',
      ml_name: 'echo',
      ml_version: '11.0.1',
      bbc_site: 'aboutthebbc',
  },
}

const analyticsHelper = analytics('example project name', options);

analyticsHelper.viewEvent('page-name', { actionName: 'page-load' });
analyticsHelper.userActionEvent('CLICKED_HERE', { campaignId: 'page-name' });

Echo Options Object

The Echo options object follows the following schema

Echo Docs: Reporting to ATI

| Key | Type | Optional? | Defaults | Value | | ----------- | ------- | --------- | -------- | ------ | | destination | string | optional | NEWS_PS | The ATI destination for your statssee Echo Desination docs | labels | object | optional | none | key-value pairs to be fed to Echo's .addLabel() function | appVersion | string | optional | none | Tells echo the version of your app | events | Array[string] | optional | none | produces custom event methods that can be used to measure seen/click interaction ratios

Default Methods

These are the methods that are supported natively by Echo

.viewEvent(countername, eventLabels)

Used to fire a page load stat

This should be called once, at the point where the page is known to have finished loading

Echo Docs: Section Echo Docs: Site Variables

| Arguments | Type | Purpose | --------- | ----- | ------- | Countername | string | Name of the page | eventLabels | object | see below

.userActionEvent(actionName, eventLabels)

Used to fire a user action stat

These can be called anywhere that a user interaction with the page needs to be monitored

Echo Docs: Valid User Actions

| Arguments | Type | Purpose | --------- | ---- | ------- | actionName | string | Name of the action | eventLabels | object | see below

Custom Event Methods

Used to track specific events in an Seen/Clicked ratio manner

By adding an events key to the options object you can supply and array of custom events that you would like monitor using ATI's impression to click ratio

.event(type, eventLabels)

| Arguments | Type | Purpose | --------- | ---- | ------- | type | 0 or 1 | 0 designates an impression, 1 designates a click | eventLabels | object | see below

The implementation of this works around some strange behaviour in Echo wherein the is_background eventLabel does not respond to being true or false. Instead, the presence of the key (regardless of the value) is taken to indicate the userActionEvent is an impression - and when it is missing the userActionEvent is counted as a click

Event Labels

| Key | Type | Default Value | Field in ATI dashboard | Purpose | | - | - | - | - | - | | container | string | 'page' | campaignId | Name the current page | metadata | string | current page name | format | Pass through additional infomation | actionType | string | '' | concatinates to the end of the Action name | Designate type of the action | personalisation | string | none | variant | Designate an experiment variant | source | string | none | advertiserId | designate the source id of the event | result | string | none | url | The url that a click event leads through to

Viewing in ATI

By default, your stats will show up in ATI under the PS_NEWS namespace.

Page View Event counts can be seen under CONTENT -> Pages

User Action Events and custom Impression Click events ratios can be viewed under CONTENT -> On-site ads

System Architecture

The package uses RequireJS to load Echo

RequireJS must be added to the window using a script tag, but this will be handled on any BBC page that already loads the Orbit header

<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>

The package then uses a functional approach to resolve the asynchronous loading of Echo without this needing to be worried about by your project

It aims to provide the same key methods that Echo uses to fire stats that we need to use

Development env

Use npm link to link a local version of this package to a project that uses this package

npm link @bbc/newslabs-helper-analytics

Tests

uses Jest

Running the tests also provides a coverage report

npm test

Release

Releases to npm should use symantic versioning

For any release, a release note outlining the changes and linking to the PR should be published through Github releases

npm version
npm publish

Contact

Please contact BBC News Labs Team if you want to get in touch