@bbc/newslabs-helper-analytics

@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 stats see 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