search

Financial-Times / n-tracking

Client-side tracking initialisation and custom events for FT.com
8 stars 2 forks source link
customer-products platforms-customer-products

readme

@financial-times/n-tracking CircleCI

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