Browser SDK

@dataframer/signals is a small browser SDK. It sends user and product events to DataFramer, and it creates the journey id that ties those events to your AI traces.

Install

npm install @dataframer/signals

Get a write key

In DataFramer, go to Settings → API Keys and generate the Signals SDK write key. This key can only send events in, never read data out, so it is safe to ship in frontend code.

The Signals SDK write key card on the API Keys tab of Settings, with Copy and Rotate buttons

Initialize once, at app start

import { DataframerSignals } from '@dataframer/signals';

const signals = new DataframerSignals({
  apiBase: 'https://df-api.dataframer.ai',
  writeKey: 'YOUR_WRITE_KEY',
});

Send events

signals.identify('user@acme.com', { plan: 'pro' });   // sets the journey's user
signals.track('RecommendationCancelled', { itemId: 'abc', reason: 'irrelevant' });
signals.group('acme');                                // the user's account or org
signals.reset();                                      // on logout: forget the user and account

Sending is best-effort and never throws an error into your app. If DataFramer rejects an event (wrong write key, invalid payload, rate limit), the SDK logs a console.warn with the reason, and the rejected event shows up with that reason under User Journeys → Live Events. During setup, that page shows whether events were rejected or never sent.

Journey ids

Every event carries a journey_id. There are two ways to get one:

Automatic (default): the SDK creates an id for you. It resets after 30 minutes of inactivity (journeyIdleMinutes).
Your own id: if you already have a natural id, such as an order id, conversation id or ticket id, you can use that:

signals.startJourney('order-1234');   // pin your own id
signals.resetJourney();               // end it, start a fresh one
signals.journeyId;                    // read the current id

Getting the journey id to your own backend

Your backend needs the journey id so it can stamp it onto your AI traces (see Server Instrumentation). How it gets there depends on whether your frontend and your backend share an origin.

Same origin: nothing to do
Different origins: two steps

If your frontend calls your backend on the origin it was served from (same scheme, host and port, for example a page on https://app.acme.com calling https://app.acme.com/api), the browser sends the SDK’s journey cookie with every request, and dataframer-journey reads it. Nothing to configure. If you stamp traces without that library, see Without this library.

If your backend is on another host, even a sibling subdomain such as api.acme.com, the browser does not send the cookie. Do two things:

Tell the SDK to forward the id as a header on requests to your backend:

const signals = new DataframerSignals({
  apiBase: 'https://df-api.dataframer.ai',
  writeKey: 'YOUR_WRITE_KEY',
  propagateHeaderTo: ['https://api.acme.com'],   // your own backend, not DataFramer
});

The SDK patches fetch and XMLHttpRequest, so every request to that URL gets an X-Journey-Id header.

Allow that header in your backend’s CORS configuration, next to the headers you already allow such as Authorization. For example, with Django’s django-cors-headers:

from corsheaders.defaults import default_headers

CORS_ALLOW_HEADERS = list(default_headers) + ['x-journey-id']

Without this, the browser blocks the request in its CORS preflight, before it reaches your server.

Content Security Policy (CSP)

If your site sets a Content-Security-Policy, allow your DataFramer API host in connect-src, or the browser blocks the SDK’s requests:

connect-src 'self' https://df-api.dataframer.ai;

A blocked request produces no SDK error. It only shows as a CSP violation in the browser console (with debug: true the SDK also warns). If events do not arrive, check this first.

Config reference

Option	Default	What it does
`apiBase`	none	Your DataFramer API base URL
`writeKey`	none	Your Signals SDK write key
`journeyIdleMinutes`	`30`	Minutes of inactivity before an automatic journey id resets
`disableAutoRotation`	`false`	Never reset the automatic journey id
`propagateHeaderTo`	`[]`	Your backend URLs, or paths on your own origin such as `/api`, that get the `X-Journey-Id` header
`debug`	`false`	Log every delivery to the console, including network failures

Next steps

Server Instrumentation

Stamp this same journey id onto your AI traces automatically.

Get started

Capture & Correlate

User Journeys & AI

Findings

Human review operations

Judges and Evaluations

Data Generation

Integrations

Programmatic Access

Install

Get a write key

Initialize once, at app start

Send events

Journey ids

Getting the journey id to your own backend

Content Security Policy (CSP)

Config reference

Next steps

Server Instrumentation

​Install

​Get a write key

​Initialize once, at app start

​Send events

​Journey ids

​Getting the journey id to your own backend

​Content Security Policy (CSP)

​Config reference

​Next steps

Server Instrumentation

Install

Get a write key

Initialize once, at app start

Send events

Journey ids

Getting the journey id to your own backend

Content Security Policy (CSP)

Config reference

Next steps