# @snowplow/tracker-core

> Core functionality for Snowplow JavaScript trackers

Latest version **4.10.2** (published 2026-09-09) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install @snowplow/tracker-core
pnpm add @snowplow/tracker-core
yarn add @snowplow/tracker-core
bun add @snowplow/tracker-core
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.10.2 |
| Published | 2026-09-09 |
| First published | 2021-03-08 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 590 |
| Maintainers | cksnp, snowplow-analytics, cogsp |
| Keywords | tracking, web analytics, events, open source |

## Links

- npm: https://www.npmjs.com/package/@snowplow/tracker-core
- Repository: https://github.com/snowplow/snowplow-javascript-tracker
- Homepage: http://bit.ly/sp-js
- Issues: https://github.com/snowplow/snowplow-javascript-tracker/issues
- npm.io page: https://npm.io/package/@snowplow/tracker-core

## Dependencies (2)

- [uuid](https://npm.io/package/uuid.md) ^11.1.1
- [tslib](https://npm.io/package/tslib.md) ^2.3.1

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 4.10.2 (latest) — 2026-09-09
- 4.1.1-dev.2 (react-native) — 2025-01-02
- 4.0.2-dev.1 (create_react_native_tracker) — 2024-11-07
- 4.0.0-beta.4 (next) — 2024-10-22
- 3.13.2-dev.0 (1185-id-service-option) — 2023-07-04
- 3.13.1-dev.0 (add-tracking-scenario-option-to-core) — 2023-06-22
- 4.10.1 — 2026-08-19
- 4.10.0 — 2026-07-27
- 4.9.0 — 2026-07-21
- 4.8.4 — 2026-07-02
- 4.8.3 — 2026-06-30
- 4.8.2 — 2026-06-17
- 4.8.1 — 2026-05-13
- 4.8.0 — 2026-04-28
- 4.7.0 — 2026-04-01
- … 90 more at https://npm.io/package/@snowplow/tracker-core/versions

## README

# Snowplow Tracker Core

[![npm version][npm-image]][npm-url]
[![License][license-image]](LICENSE)

Core module to be used by Snowplow JavaScript based trackers.

## Maintainer quick start

Part of the Snowplow JavaScript Tracker monorepo.  
Build with [Node.js](https://nodejs.org/en/) (18 - 20) and [Rush](https://rushjs.io/).

### Setup repository

```bash
npm install -g @microsoft/rush 
git clone https://github.com/snowplow/snowplow-javascript-tracker.git
rush update
```

### Building Tracker Core

```bash
cd libraries/tracker-core
rushx build
```

### Running tests

```bash
rushx test
```

## Package Installation

With npm:

```bash
npm install @snowplow/tracker-core
```

## Usage

### CommonJS Example

```js
const trackerCore = require('@snowplow/tracker-core').trackerCore;

// Create an instance with base 64 encoding set to false (it defaults to true)
const core = trackerCore({
    base64: false
});
```

### ES Module Example

```js
import { trackerCore } from '@snowplow/tracker-core';

// Create an instance with base 64 encoding set to false (it defaults to true)
const core = trackerCore({
    base64: false
})
```

### Example

```js
// Add a name-value pair to all payloads
core.addPayloadPair('vid', 2);

// Add each name-value pair in a dictionary to all payloads
core.addPayloadDict({
    'ds': '1160x620',
    'fp': 4070134789
});

// Add name-value pairs to all payloads using convenience methods
core.setTrackerVersion('js-3.6.0');
core.setPlatform('web');
core.setUserId('user-321');
core.setColorDepth('24');
core.setViewport('600', '400');
core.setUseragent('Snowplow/0.0.1');

// Track a page view with URL and title
const pageViewPayload = core.track(
    buildPageView({
        pageUrl: 'http://www.example.com',
        pageTitle: 'landing page',
    })
);

console.log(pageViewPayload);
/*
{
    'e': 'pv',
    'url': 'http://www.example.com',
    'page': 'landing page',
    'uid': 'user-321',
    'vid': 2,
    'ds': '1160x620',
    'fp': 4070134789,
    'tv': 'js-3.6.0',
    'p': 'web',
    'cd': '24',
    'vp': '600x400',
    'ua': 'Snowplow/0.0.1',
    'dtm': '1406879959702',                          // timestamp
    'eid': 'cd39f493-dd3c-4838-b096-6e6f31015409'    // UUID
}
*/

// Stop automatically adding tv, p, and dtm to the payload.
core.resetPayloadPairs({});

// Track an unstructured event
const selfDescribingEventPayload = core.track(
    buildSelfDescribingEvent({
        event: {
            'schema': 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-0',
            'data': {
                'targetUrl': 'http://www.destination.com',
                'elementId': 'bannerLink'
            }
        }
    })
);

console.log(selfDescribingEventPayload);
/*
{
    'e': 'ue',
    'eid': '4ed5da6b-7fff-4f24-a8a9-21bc749881c6',
    'dtm': '1659086693634',
    'ue_pr': "{\"schema\":\"iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0\",\"data\":{\"schema\":\"iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-0\",\"data\":{\"targetUrl\":\"http://www.destination.com\",\"elementId\":\"bannerLink\"}}}"
}
*/
```

## Other features

Core instances can be initialized with a configuration object. `base64` Determines whether custom contexts and unstructured events will be base 64 encoded.  `corePlugins` are used to intercept payload creation and add contexts on every event. `callback` is an optional callback function which gets applied to every payload created by the instance.

```js
const core = trackerCore({
    base64: true,
    corePlugins: [/* Your plugins here*/],
    callback: console.log
});
```

The above example would base 64 encode all unstructured events and custom contexts and would log each payload to the console.

Use the `setBase64Encoding` method to turn base 64 encoding on or off after initializing a core instance:

```js
const core = trackerCore(); // Base 64 encoding on by default

core.setBase64Encoding(false); // Base 64 encoding is now off
```

## Documentation

For more information on the Snowplow JavaScript Tracker Core's API, view its [docs page][docs].

## Copyright and license

Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).

Copyright (c) 2022 Snowplow Analytics Ltd, 2010 Anthon Pang.

All rights reserved.

[npm-url]: https://www.npmjs.com/package/@snowplow/tracker-core
[npm-image]: https://img.shields.io/npm/v/@snowplow/tracker-core
[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/node-js-tracker/javascript-tracker-core/
[osi]: https://opensource.org/licenses/BSD-3-Clause
[license-image]: https://img.shields.io/npm/l/@snowplow/tracker-core

---
_Source: https://npm.io/package/@snowplow/tracker-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._