# @financial-times/n-tracking

> Client-side tracking initialisation for FT.com apps

Latest version **7.10.0** (published 2026-06-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @financial-times/n-tracking
pnpm add @financial-times/n-tracking
yarn add @financial-times/n-tracking
bun add @financial-times/n-tracking
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 7.10.0 |
| Published | 2026-06-25 |
| First published | 2019-04-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 16.x \|\| 18.x |
| Dependencies | 7 |
| Unpacked size | 85.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | the-ft, rowanmanning, chee, alexwilson, aendra, emmalewis, notlee, hamza.samih, robertboulton, leila.micollier, robgodfrey |

## Links

- npm: https://www.npmjs.com/package/@financial-times/n-tracking
- Repository: Financial-Times/n-tracking.git
- npm.io page: https://npm.io/package/@financial-times/n-tracking

## Dependencies (7)

- [web-vitals](https://npm.io/package/web-vitals.md) ^3.4.0
- [ready-state](https://npm.io/package/ready-state.md) ^2.0.5
- [@financial-times/o-grid](https://npm.io/package/@financial-times/o-grid.md) ^5.0.0
- [@financial-times/o-tracking](https://npm.io/package/@financial-times/o-tracking.md) ^4.11.0
- [@financial-times/o-viewport](https://npm.io/package/@financial-times/o-viewport.md) ^4.0.0
- [@financial-times/privacy-us-privacy](https://npm.io/package/@financial-times/privacy-us-privacy.md) ^2.1.0
- [@financial-times/ads-personalised-consent](https://npm.io/package/@financial-times/ads-personalised-consent.md) ^5.3.3

## Recent versions

- 7.10.0 (latest) — 2026-06-25
- 6.1.0-beta.1 (pre-release) — 2023-01-05
- 8.0.0 — 2026-06-23
- 7.9.0 — 2025-11-07
- 7.8.0 — 2025-08-28
- 7.7.0 — 2025-06-02
- 7.6.0 — 2025-02-11
- 7.5.0 — 2025-01-22
- 7.4.0 — 2024-03-07
- 7.3.0 — 2023-12-12
- 7.2.3 — 2023-11-28
- 7.2.2 — 2023-10-30
- 7.2.1 — 2023-10-27
- 7.2.0 — 2023-09-26
- 7.1.1 — 2023-09-21
- … 36 more at https://npm.io/package/@financial-times/n-tracking/versions

## README

# @financial-times/n-tracking [![CircleCI](https://circleci.com/gh/Financial-Times/n-tracking/tree/main.svg?style=svg)](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');

<CoreTracking {...options} />
```

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 `<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](./docs) 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](#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

---
_Source: https://npm.io/package/@financial-times/n-tracking · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._