README

@financial-times/n-tracking

This package provides tracking initialisation and custom events for FT.com. On the client-side it configures o-tracking (which is used to capture and send tracking events to Spoor) and for the server-side it provides components which render fallback tracking pixels .

Getting started

This package is for client-side and server-side use and is distributed on npm.

npm install -S @financial-times/n-tracking

After installing the package you can import the tracking component into your code:

Client-side integration

Configure o-tracking

This package can be used on the client-side. Initialise the component with configuration options.

import * as nTracking from '@financial-times/n-tracking';
const options = {}
const oTracking = nTracking.init(options);

Send custom events

import * as nTracking from '@financial-times/n-tracking';
const context = { customData: 12345 }
nTracking.broadcast('oTracking.event', {
  category: 'page',
  action: 'custom-event',
  ...context
});

Server-side integration

On the server-side a JSX component embeds tracking pixels into the page which send page view events for any visitors which do not support JS or fail to cut the mustard.

const { CoreTracking } = require('@financial-times/n-tracking');

<CoreTracking {...options} />

To initialise the component you'll need to provide it with several configuration options.

Client-side API

`init(options)`

Configures o-tracking with the given options, triggers a page view event, initialises click tracking, and returns the instance of o-tracking.

`broadcast(name, data)`

Creates a CustomEvent with the given name and data and dispatches it from the document <body> element. It is intended to be used to trigger oTracking.event events.

`trackers.{tracker}()`

There are several custom tracking features provided by this library. See the docs folder for more information about these.

Server-side API

`<CoreTracking />`

Renders a <noscript> and inline <script> element to embed fallback tracking pixels into the page which can be used when the client-side JS fails to run. It accepts the same options as the client-side code.

Options

Property	Type	Required	Description
`appContext`	Object	Yes	FT.com App Context data describing the current page which will be appended to all captured events.
`extraContext`	Object	No	Additional data describing the current page which will be appended to all captured events.
`pageViewContext`	Object	No	Additional data to append to the page view event only

Automatically inferred data

Marketing query string parameters inc. cost-per-click and segment IDs
User data inc. layout, screen orientation, and connection type
Error page parameters inc. error code and error message

Usage no npm install needed!