@throughlinehq/browser

Record Throughline Events from your frontend, for the Contact whose session it is.

npm install @throughlinehq/browser

It has no runtime dependencies and ships about 2.5 kB minified and gzipped.

How it fits together

A browser may only record Events. It cannot create, read, export or erase Contacts: that stays on your backend with @throughlinehq/server.

A publishable key alone says which site may record Events, never who is using the page, so anyone could name any Contact. Your server therefore proves the identity by computing an IdentityHash for the signed-in user and handing it to the page.

1. On your server

import { identityHash } from '@throughlinehq/server';

const hash = await identityHash({
  signingSecret: process.env.THROUGHLINE_SIGNING_SECRET!,
  externalId: user.id,
});

Find the signing secret and its key ID under Settings → API keys → Signing secret. Pass the hash, the key ID and the externalId down with the page, or store the hash beside the user: it never changes for a Contact and does not expire.

Never compute the IdentityHash in the browser. Doing so ships the signing secret to every visitor, and any one of them can then record Events as anyone.

2. In the browser

import { ThroughlineBrowserClient } from '@throughlinehq/browser';

const throughline = new ThroughlineBrowserClient({
  publishableKey: 'pk_live_…',
  externalId: user.id,
  identityHash: user.throughlineIdentityHash,
  identityKeyId: user.throughlineIdentityKeyId,
});

await throughline.track({ eventName: 'pricing_viewed', properties: { plan: 'pro' } });

The client defaults to https://browser.api.throughline.dk; you never pass a base URL.

The publishable key is expected to be visible in your bundle and in the network tab. That is safe by design: it can only record Events, only from the origins you list on the key, and only for a Contact your server has signed. Allow only the origins you actually serve from.

What it does not do

• No anonymous tracking. There is no visitor id, no aliasing and no queue of events recorded before the Contact is known. You supply the identity your application already holds.
• No cookie and no storage. It sets no cookie and writes no persistent identifier, to localStorage or anywhere else, so adopting it does not oblige you to change your consent banner.
• No Contact methods. The browser surface has none.

Leaving the page

Events still in flight when the page is hidden or unloaded are re-sent immediately with fetch(…, { keepalive: true }), so they survive navigation. That re-send is a single attempt that never waits on a retry backoff. Each Event keeps its DedupKey, so a re-send of one that had already landed collapses on the server for 60 seconds.

A keepalive request is capped by the browser at 64 kB, so a page that still has more than that in flight when it unloads may lose the excess.

Frameworks

Each adapter only holds one client and shares it with your components. The frameworks are optional peer dependencies, so installing the package pulls in none of them.

React

import { ThroughlineProvider, useThroughline } from '@throughlinehq/browser/react';

<ThroughlineProvider key={user.id} publishableKey="pk_live_…" externalId={user.id} identityHash={user.throughlineIdentityHash} identityKeyId={user.throughlineIdentityKeyId}>
  <App />
</ThroughlineProvider>;

const throughline = useThroughline();

Vue

import { createThroughline, useThroughline } from '@throughlinehq/browser/vue';

createApp(App).use(createThroughline({ publishableKey: 'pk_live_…', externalId: user.id, identityHash, identityKeyId }));

const throughline = useThroughline();

Angular

import { injectThroughline, provideThroughline } from '@throughlinehq/browser/angular';

bootstrapApplication(AppComponent, {
  providers: [provideThroughline({ publishableKey: 'pk_live_…', externalId: user.id, identityHash, identityKeyId })],
});

private readonly throughline = injectThroughline();

Errors

Every error extends ThroughlineError.

| Error | When | | -------------------------------- | ------------------------------------------------------------------------------- | | ThroughlineAuthenticationError | The publishable key, its origin allowlist or this page's origin was rejected. | | ThroughlineScopeError | The IdentityHash does not match externalId, or its key is unknown or revoked. | | ThroughlineRejectedEventsError | The Contact does not exist, so nothing was recorded. | | ThroughlineRateLimitError | The origin's request budget is spent and the call could not be retried in time. | | ThroughlineNetworkError | The API could not be reached, or the call ran out of time. | | ThroughlineInvalidRequestError | The event or an option was malformed. | | ThroughlineServerError | The API answered with a 5xx after the retries were spent. |

Options

| Option | Default | Meaning | | ---------------- | ------------------------------------ | -------------------------------------------------------------------- | | publishableKey | — | The pk_live_… key from Settings → API keys. | | externalId | — | The externalId of the Contact whose session this is. | | identityHash | — | The IdentityHash your server computed for externalId. | | identityKeyId | — | The id of the key whose signing secret produced the hash. | | baseUrl | https://browser.api.throughline.dk | Where the browser API lives. | | fetch | global fetch | A test double or runtime-specific implementation. | | timeoutMs | 10000 | Total time one track call may take, retries included. Under 60000. | | maxRetries | 3 | How many times a failed track call may be retried. |

License

MIT