# analytics-client

> Convenient builders to compose analytics tools

Latest version **3.2.0** (published 2026-03-26) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install analytics-client
pnpm add analytics-client
yarn add analytics-client
bun add analytics-client
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2026-03-26 |
| First published | 2019-10-14 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 325.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 5 |
| Maintainers | balena.io |

## Links

- npm: https://www.npmjs.com/package/analytics-client
- Repository: https://github.com/balena-io-modules/analytics-client
- Homepage: https://github.com/balena-io-modules/analytics-client#readme
- Issues: https://github.com/balena-io-modules/analytics-client/issues
- npm.io page: https://npm.io/package/analytics-client

## Dependencies (4)

- [js-cookie](https://npm.io/package/js-cookie.md) ^3.0.1
- [@amplitude/analytics-browser](https://npm.io/package/@amplitude/analytics-browser.md) ^2.16.0
- [@amplitude/engagement-browser](https://npm.io/package/@amplitude/engagement-browser.md) 1.0.2
- [@amplitude/plugin-user-agent-enrichment-browser](https://npm.io/package/@amplitude/plugin-user-agent-enrichment-browser.md) ^1.0.1

## Recent versions

- 3.2.0 (latest) — 2026-03-26
- 3.2.0-build-expose-amplitude-object-to-global-scope-e081578579e2ae1f87b3a59a38fcb027cf4ca59a-2 (build-expose-amplitude-object-to-global-scope) — 2026-03-26
- 3.1.3-build-add-npm-oidc-permissions-4e1abaeb6aa5e16ed530389805b35f5f234bcdc6-1 (build-add-npm-oidc-permissions) — 2026-02-18
- 3.1.2-build-update-engagement-plugin-19c1345b4929adba16057446014b9c2385b22821-1 (build-update-engagement-plugin) — 2025-09-09
- 3.2.0-build-add-experiment-client-init-fn-35e2bf291d1d274a97e0eff90782b28695dad172-1 (build-add-experiment-client-init-fn) — 2025-09-08
- 3.1.1-build-re-add-attribution-capture-77f34371d1a5f932a4f1a47eb272f34e316ecb24-1 (build-re-add-attribution-capture) — 2025-06-23
- 3.1.0-build-add-engagement-sdk-back-dacf8c0ab4ca5f0fb7dfa4c34dbe747a37a176b4-1 (build-add-engagement-sdk-back) — 2025-04-30
- 3.0.0-build-bump-amplitude-analytics-browser-v2-e491ef9750a0ce9ccb11365ee5e95d6fb6925e20-1 (build-bump-amplitude-analytics-browser-v2) — 2025-04-29
- 2.1.0-build-guides-and-surveys-bf89797f90db8d3c161d963f287424e93e9f5998-1 (build-guides-and-surveys) — 2025-04-16
- 2.0.2-build-klutchell-patch-1-e125e54e758b1778190ca6b832acb41a33e6b42e-1 (build-klutchell-patch-1-e125e54e758b1778190ca6b832acb41a33e6b42e) — 2023-07-14
- 2.0.1-adds-original-ts-bundle-for-source-map-92346366bf81101d28f4dc3e80e3f7c4ee3f8e00-1 (adds-original-ts-bundle-for-source-map) — 2022-11-10
- 2.0.0-feature-use-ts-client-cb95c7f372950bd316450408e877f49be5db21ac-1 (feature-use-ts-client-cb95c7f372950bd316450408e877f49be5db21ac) — 2022-11-02
- 2.0.0-feature-use-ts-client-7e0074d7ec0239e5b9f6e8bc4ee02a0892d1ebd3-1 (feature-use-ts-client-7e0074d7ec0239e5b9f6e8bc4ee02a0892d1ebd3) — 2022-11-02
- 2.0.0-feature-use-ts-client-1bf7612a8826868df270bf191499b6fd0aa25f5a-1 (feature-use-ts-client-1bf7612a8826868df270bf191499b6fd0aa25f5a) — 2022-10-28
- 2.0.0-feature-use-ts-client-99530d5c885a4814b8967dbf314f81eb7b6131af (feature-use-ts-client-99530d5c885a4814b8967dbf314f81eb7b6131af) — 2022-10-25
- … 157 more at https://npm.io/package/analytics-client/versions

## README

Analytics client
================

Client part of analytics services used at balena.
The analytics client is a component that integrates into the [analytics-backend](https://github.com/balena-io/analytics-backend). Together they're responsible for processing the analytics tracking events before forwarding them to the relevant parties, referred to here as *the final destinations*.
Currently the only final destination is Amplitude. We have plans to support more final destinations going forward, like Sentry.

## Installation

```
npm install --save analytics-client
```


## Client Initialization
The first thing to do is create and initialize an `analytics client`.

Since most of balena products are maintained on different components/repos (ie Hub, Marketing Site, Cloud, etc) we need to make sure that
when someone navigates between components we can keep identifying it as a same id.

So to achieve that we will need to:

```typescript
import { AnalyticsUrlParams, createClient} from 'analytics-client';

const urlParamsHandler = new AnalyticsUrlParams();

// This will handle any passed device id (d_id) param on the URL if it exists, save it on a cookie and return a "clean" query string without the d_id param
const newQuery = urlParamsHandler.consumeUrlParameters(window.location.search) ?? null;

// Then if there was any passed device id we can obtain them like this.
// passedDeviceId is either the first d_id param passed on the URL or null
const passedDeviceId = urlParamsHandler.getPassedDeviceId()

// Now that we checked for any passed device_id we can proceed with creating and initializing the client
const client = createClient({
    endpoint: 'data.balena-cloud.com', // use 'data.balena-staging.com' for testing
    projectName: 'balena-project', // unique identifier that analytics-backend expects
    componentName: 'etcher-featured-project', // short unique name of component
    componentVersion: require('./package.json').version, // (optional) automated version reporting
    deviceId: passedDeviceId,
})

// A newly created client is passed to the `AnalyticsUrlParams` to make it fully functional.
urlParamsHandler.setClient(client);
```

## Usage
Tracking a page view and a navigation click. The following reports an event named `[EFP] Page View` and another event with `[EFP] Navigation Click` with default properties.

```typescript
import {createWebTracker } from 'analytics-client';

const webTracker = createWebTracker(client, 'EFP'); // 2nd parameter defines the prefix of event names
webTracker.trackPageView();
webTracker.trackNavigationClick('https://hub.balena.io'); // User clicks on a button to navigate to the Hub
```

Here is an example how a product like CLI would identify a user and report a login event (`[CLI] Login`) with certain event properties related to the login action.

```typescript
import { createClient } from 'analytics-client';

const client = createClient({
    endpoint: 'data.balena-cloud.com', // use 'data.balena-staging.com' for testing
    projectName: 'balena-project', // unique identifier that analytics-backend expects
    componentName: 'balena-cli', // short unique name of component
    componentVersion: require('./package.json').version, // (optional) automated version reporting
});

// user authenticates as part of the product flow

client.setUserId('balenaCloudUsername');

client.track('Login', {
    balenaUrl: 'balena-cloud.com',
    loginType: 'web-auth',
    node: 'v10.21.0',
})
```

URL query parameters tool.

```typescript
import { AnalyticsUrlParams } from 'analytics-client';

const urlParamsHandler = new AnalyticsUrlParams(mixpanel);

urlParamsHandler.consumeUrlParameters(window.location.search);

const signupUrl = '/signup?' + urlParamsHandler.getDeviceIdsQueryString();
```

UI experiments definition.
```typescript
import { createClient, LocalExperiment } from 'analytics-client';

const client = createClient({projectName: 'my-project'});

type Variation = 'modal' | 'sidebar-left' | 'sidebar-right';
const experiment = new LocalExperiment<Variation>('WelcomeUI', client)
    .define('modal', 50)
    .define('sidebar-left', 25)
    .define('sidebar-right', 25);

switch (experiment.engage(client.deviceId())) {
    case 'modal':
        showModal();
        break;
    // ...
}
```

## Using without npm packages

Load the script from unpkg CDN (replacing `{version}` with an actual version you need to use):
```html
<script src="https://unpkg.com/analytics-client@{version}/dist/bundle.js"></script>
```
Then use the `analyticsClient` variable:
```js
const urlParamsHandler = new analyticsClient.AnalyticsUrlParams();
```

## Configuration

We use environment configuration on the [analytics-backend](https://github.com/balena-io/analytics-backend) to mask the actual API tokens of the final destination services of these events.
We expose easy to remember names to map the destination specific tokens to `projectName` variable used as part of client initialization. analytics-backend uses the value of `projectName` to reason where to pipe the event flow.
The masking helps with preventing abuse and the mapping makes the configuration more flexible to support multiple final destinations.
Reach out to the data team when in doubt which project to use or if you need to define a new project.

In the final destinations, we separate staging and production environments. We use the same `projectName` value but different tokens to differentiate the production and staging environments. So you only need to update `endpoint` to pick the right destination.

Use the staging environment for testing purposes by setting `endpoint` in the `createClient` initialization to `data.balena-staging.com`. Once you are happy with your tests and ready to go live, update the `endpoint` to `data.balena-cloud.com` for production environment.

Additionally, identify your component using the parameter `componentName`. It's best to keep the value short yet descriptive.

Please ask Operation folks for `#access` to the relevant project in your final destination so you can validate that the tracked events show as expected.

Finally, there is the optional configuration parameter `componentVersion` to track the version of a component sending each event. This is useful to track changes across new component versions so we strongly recommend tracking it.

## Web tracker

[`WebTracker`](src/web.ts) exposes an events tracking interface suitable for web apps. It provides a simple `Page View` event tracking with page loading metrics via `trackPageView`.

When initializing `createWebTracker`, set `prefix` as a short string that describes your project. All events tracked by `WebTracker` will have this `prefix` in their name.
We use this prefixing method to identify and group events in the final destination for organization purposes and helping the analysts traverse the events with ease.
This is especially useful when there are multiple components sending events to the same project in the final destination. To give an example, our marketing website, docs pages and blog all send `Page View` event but these are prefixed respectively `Marketing`, `Docs` and `Blog`. So the final event name is `[Marketing] Page View`, `[Docs] Page View`, etc. Furthermore, this method makes it easier to identify all the `Marketing` events.

## Identifying users

By default the client tracks `deviceId` to identify the current device of the end user. `deviceId` is a UUID generated automatically by the client. Use `setUserId` method to identify authenticated user. At least one of these identifiers is required to successfully track an event.

In most cases the device refers to the browser of the user (or Electron application for the case of Etcher). By persisting the `deviceId` in the local storage, we are able to identify the events coming from the same user in order to create a timeline of component usage.

It is possible to generate a new device identifier and also override an existing device identifier. Additionally, when we record multiple device identifiers along with the same user identifier, we are able to link multiple event timelines coming from various devices belonging to the same user.
For instance, a balenaCloud user might login to the dashboard from multiple browsers and also use balenaCLI. We would like to create a coherent timeline that captures all their activity and display it under the same user in order to make a sound analysis of their balena platform usage. As long as all the components `setUserId` as soon as the authentication happens, we are able to link all the events with separate `deviceId` values that came *even before* the authentication on the backend side.

[`AnalyticsUrlParams`](src/url-params.ts) helps with linking anonymous `deviceId` values that each component sends individually.
For instance we use this method to link Etcher users clicking on EFP link to land on our blog website and eventually signup to balenaCloud.
When the user clicks on the blog link in EFP, we append the `deviceId` generated by EFP component to the URL.
Then the blog parses the URL to match EFP `deviceId` with blog `deviceId` (essentially the `deviceId` associated with the browser that opened the blog website).
In a similar fashion, the signup links on the blog website also includes EFP `deviceId` as well as blog `deviceId`.
When the user lands on balenaCloud dashboard and authenticates, we link all the user activity and list it under the same timeline.
We need to make these jumps as there are 3 components tracking events and there are multiple domains involved.
The benefit is we are able to look into a user's EFP and blog activity before signing up to balenaCloud.


## Questions?

Reach out to the data team in `r/analytics` flow for guidance and troubleshooting.

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