Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



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

Version published




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


npm i @bbc/newslabs-helper-analytics


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: '',
      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

destinationstringoptionalNEWS_PSThe ATI destination for your stats
see Echo Desination docs
labelsobjectoptionalnonekey-value pairs to be fed to Echo's .addLabel() function
appVersionstringoptionalnoneTells echo the version of your app
eventsArray[string]optionalnoneproduces 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

CounternamestringName of the page
eventLabelsobjectsee 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

actionNamestringName of the action
eventLabelsobjectsee 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)

type0 or 10 designates an impression, 1 designates a click
eventLabelsobjectsee 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

KeyTypeDefault ValueField in ATI dashboardPurpose
containerstring'page'campaignIdName the current page
metadatastringcurrent page nameformatPass through additional infomation
actionTypestring''concatinates to the end of the Action nameDesignate type of the action
personalisationstringnonevariantDesignate an experiment variant
sourcestringnoneadvertiserIddesignate the source id of the event
resultstringnoneurlThe 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=""></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


uses Jest

Running the tests also provides a coverage report

npm test


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


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



Last updated on 01 Aug 2019

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc