https://github.com/financial-times/n-tracking
Client-side tracking initialisation and custom events for FT.com
https://github.com/financial-times/n-tracking
customer-products platforms-customer-products
Last synced: 8 months ago
JSON representation
Client-side tracking initialisation and custom events for FT.com
- Host: GitHub
- URL: https://github.com/financial-times/n-tracking
- Owner: Financial-Times
- Created: 2019-04-03T15:47:50.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-08-27T10:33:39.000Z (10 months ago)
- Last Synced: 2025-08-27T19:52:50.031Z (10 months ago)
- Topics: customer-products, platforms-customer-products
- Language: JavaScript
- Homepage:
- Size: 1.13 MB
- Stars: 8
- Watchers: 44
- Forks: 1
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# @financial-times/n-tracking [](https://circleci.com/gh/Financial-Times/n-tracking/tree/main)
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 .
[o-tracking]: https://github.com/Financial-Times/o-tracking
[Spoor]: https://spoor-docs.herokuapp.com/
## Getting started
This package is for client-side and server-side use and is distributed on npm.
```sh
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](#options).
```js
import * as nTracking from '@financial-times/n-tracking';
const options = {}
const oTracking = nTracking.init(options);
```
**Send custom events**
```js
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.
```jsx
const { CoreTracking } = require('@financial-times/n-tracking');
```
To initialise the component you'll need to provide it with several [configuration options](#options).
## Client-side API
### `init(options)`
Configures [o-tracking] with the given [options](#options), triggers a page view event, initialises click tracking, and returns the instance of [o-tracking].
### `broadcast(name, data)`
Creates a [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) with the given name and data and dispatches it from the document `` 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](./docs) for more information about these.
## Server-side API
### ``
Renders a `` and inline `` 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](#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
[FT.com App Context]: https://github.com/Financial-Times/dotcom-page-kit/blob/HEAD/packages/dotcom-server-app-context/schema.md
## 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