Browser SDK - DataFramer

@dataframer/signals is a small browser SDK that sends user/product events to DataFramer and generates the journey id that ties those events to your AI traces. It follows the same track/identify/group shape as Segment, so if your app already uses Segment, this will feel familiar.

Install

npm install @dataframer/signals

Get a write key

In your DataFramer dashboard: Profile → Signal Write Keys → create a key. This key is public-safe: it’s meant to sit in frontend code and can only send events in, not read data out.

Initialize once, at app start

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

const signals = new DataframerSignals({
  apiBase: 'https://your-dataframer-api',   // where /api/signals/* lives
  writeKey: 'YOUR_WRITE_KEY',
});

Send events

signals.track('RecommendationCancelled', { itemId: 'abc', reason: 'irrelevant' });
signals.identify('[email protected]', { plan: 'pro' });   // sets the journey's user
signals.group('acme');                                 // account/org rollup

Sending is best-effort: it will never throw an error into your app.

Journey ids

Every event you send carries a journey_id automatically:

Default: a journey id is created for you and stored in a cookie + localStorage. It resets after 30 minutes of inactivity.
Better, use your own id: if you already have a natural id (order id, conversation id, ticket id), pin it:

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

CORS: when you need it, and when you don’t

The SDK sends events with a normal browser fetch call to apiBase. Whether you need to touch CORS depends on where your backend lives:

Same site: nothing to do
Different domains: two steps

If your frontend and your backend are on the same domain (or share a parent domain, like app.acme.com and api.acme.com with cookies set on .acme.com), the journey id rides along as a cookie automatically. You don’t need to configure anything.

If your frontend and backend are on unrelated domains (e.g. a SaaS product frontend calling a customer’s own API on a different domain), cookies won’t reliably cross that boundary. Do two things:

Tell the SDK to forward the id as a header, by listing your API’s URL:

const signals = new DataframerSignals({
  apiBase: 'https://your-dataframer-api',
  writeKey: 'YOUR_WRITE_KEY',
  propagateHeaderTo: ['https://your-backend'],   // your API's origin
});

This patches fetch/XHR so any request to https://your-backend automatically gets an X-Journey-Id header attached.

Allow that header in your backend’s CORS config, the same way you’d already allow Authorization or Content-Type. 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’s CORS preflight will reject the request before it reaches your server. This is exactly what we had to add for our own dashboard, since our frontend and backend sit on different domains.

Config reference

Option	Default	What it does
`apiBase`	none	Base URL where `/api/signals/*` lives
`writeKey`	none	Your public write key
`journeyIdleMinutes`	`30`	Minutes of inactivity before an auto journey id resets
`disableAutoRotation`	`false`	Never auto-reset the journey id
`propagateHeaderTo`	`[]`	Origins to attach the `X-Journey-Id` header to (see CORS above)

Next steps

Server Instrumentation

Stamp this same journey id onto your AI traces automatically.

​Install

​Get a write key

​Initialize once, at app start

​Send events

​Journey ids

​CORS: when you need it, and when you don’t

​Config reference

​Next steps