Browser SDK

@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.

Install

npm install @dataframer/signals

Get a write key

In your DataFramer dashboard, go to Settings → Keys and create a Signals SDK Write Key. On DataFramer hosted by us that’s app.dataframer.ai/settings?tab=keys; on a private deployment it’s the same Settings → Keys page on your own instance. This key is meant to 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.identify('user@acme.com', { plan: 'pro' });   // sets the journey's user
signals.track('RecommendationCancelled', { itemId: 'abc', reason: 'irrelevant' });

Sending is best-effort: it will never throw an error into your app. If the server rejects an event (bad write key, failed validation, rate limit), the SDK logs a console.warn with the status and reason, and the rejected event appears with its reason in your dashboard under User Journeys → Live Events — so you can tell the difference between “wired wrong” and “nothing sent yet” while setting up.

Journey ids

Every event you send carries a journey_id automatically:

Default: a journey id is created for you. By default, it resets after 30 minutes of inactivity. It is configurable.
Use your own id: if you already have a natural id (order id, conversation id, ticket id), you can use that:

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: getting the journey id to your own backend

This section is about attaching the journey id to the requests your frontend makes to your own backend, so your server can stamp that id onto your AI traces. How the journey id reaches your backend depends on where your frontend and your backend live.

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 your backend are on different domains (for example, your product frontend calling your own API on a separate domain), cookies do not reliably cross that boundary. Do two things:

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

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

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.

Content Security Policy (CSP)

If your site sets a Content-Security-Policy, the browser will block the SDK’s requests unless your DataFramer API host is allowed in the connect-src directive:

connect-src 'self' https://your-dataframer-api;

A blocked request produces no SDK error by default — it only shows up as a CSP violation in the browser console (with debug: true the SDK also warns about the failed delivery). If events aren’t arriving, this is one of the first things to check.

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)
`debug`	`false`	Console-log every delivery, including network-level failures (server rejections warn regardless)

Next steps

Server Instrumentation

Stamp this same journey id onto your AI traces automatically.

Overview

Capture & Correlate

User Journeys & AI

Findings

Human review operations

Judges, Datasets, and Evaluations

Generation

Developer Access

Release Notes

Install

Get a write key

Initialize once, at app start

Send events

Journey ids

CORS: 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

​CORS: 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

CORS: getting the journey id to your own backend

Content Security Policy (CSP)

Config reference

Next steps