JavaScript SDK

@traffical/js-client is the framework-agnostic browser SDK. It fetches the config bundle, resolves parameters in the browser, tracks exposure events, and manages anonymous-user identity automatically. If you’re using React or Svelte, prefer the React SDK or Svelte SDK — they wrap this client with framework-native APIs.

Installation

npm install @traffical/js-client

pnpm add @traffical/js-client

yarn add @traffical/js-client

Setup

import { createTrafficalClient } from "@traffical/js-client";

const traffical = await createTrafficalClient({
  orgId: "org_acme",
  projectId: "proj_marketplace",
  env: "production",
  apiKey: "traffical_pk_...",
});

Use an publishable SDK key (traffical_pk_...) in client code. It fetches the config bundle and sends events, and cannot modify configuration — safe to ship in a client bundle.

Resolving parameters

const params = traffical.getParams(
  { userId: "user_789" },
  {
    "homepage.hero_headline": "Welcome back",
    "homepage.show_banner": true,
  },
);

document.querySelector("h1")!.textContent = params["homepage.hero_headline"];

Both getParams(context, defaults) and decide(context, defaults) take context first, defaults second, and both are synchronous. In the browser you can usually omit the unit key — the SDK fills it from the auto-generated stable ID (see below).

The legacy object-bag form — getParams({ context, defaults }) / decide({ context, defaults }) — still works but is deprecated. Prefer the positional form.

An exposure event is emitted automatically the first time a user/assignment combination is resolved in a session.

Anonymous users and `identify`

Browser-side experimentation often needs to resolve parameters before a user is logged in. To make that work without you having to think about it, the browser SDK auto-generates a stable UUID on first visit, stores it in localStorage (with a cookie fallback), and fills the project’s unit-key slot with that value whenever the caller doesn’t pass one. So if the project’s unit key is userId, the SDK effectively passes context.userId = "<auto-generated-uuid>" on every pre-login resolution. Bucketing works, exposure events fire, the user gets a stable assignment for as long as their localStorage persists. When the user logs in, call identify(realUserId):

traffical.identify("user_789");

This overwrites the stored stable ID with the real userId. Every subsequent resolution uses the new value.

Bucketing changes at login. The pre-login bucket and the post-login bucket are computed from different inputs (hash(uuid + layerId) vs hash("user_789" + layerId)) — they almost always land in different allocations. A user who saw the treatment allocation while anonymous may see control after logging in, and vice versa.This is unavoidable with a single unit of randomization per project. There’s no “anonymous-to-identified” continuity layer: the SDK doesn’t remember which bucket the stable ID was in and remap the userId to match. If you need user-stable assignments to persist across login, run the policy on logged-in users only — gate the policy with a condition that the unit key matches a real user-ID format, or have your backend force identify() before the SDK ever resolves the parameter.

You can read the current stable ID with traffical.getStableId(). After identify(), this returns the value you passed in.

Tracking events

track(event, properties?, options?) — the event name first, an optional properties payload second, and an options bag (unitKey, decisionId, value, values, eventTimestamp) third. In the browser unitKey defaults to the current stable ID, so you rarely pass it:

traffical.track("signup");

traffical.track("purchase", { order_total: 29.99, currency: "USD" }, { value: 29.99 });

Events are batched in memory and flushed in the background.

Lifecycle

createTrafficalClient (async) awaits the first bundle fetch. When you can’t await at construction, use createTrafficalClientSync and await readiness before the first resolution:

import { createTrafficalClientSync } from "@traffical/js-client";

const traffical = createTrafficalClientSync({ orgId, projectId, env, apiKey });
await traffical.initialize();
await traffical.waitForReady();   // resolves once config loads — or fails open; never hangs

Force a flush of queued events (e.g. after a critical conversion, before navigating):

await traffical.flushEvents();

Tear the client down with the single teardown verb, close(). It stops the background refresh and awaits a final event flush before returning (on page unload it falls back to sendBeacon so the last batch still ships):

await traffical.close();

destroy() still exists but is deprecated — prefer close(), which awaits the final flush.

Options

Option	Type	Default	Description
`orgId`	`string`	required	Organization ID
`projectId`	`string`	required	Project ID
`env`	`string`	required	Environment name
`apiKey`	`string`	required	Publishable Publishable SDK key (`traffical_pk_...`) — safe in a client bundle
`baseUrl`	`string`	`https://sdk.traffical.io`	SDK API base URL
`refreshIntervalMs`	`number`	`60000`	Bundle refresh interval
`localConfig`	`ConfigBundle`	—	Embedded bundle for cold-start
`evaluationMode`	`"bundle" \| "server"`	`"bundle"`	See how it works
`attributionMode`	`"cumulative" \| "decision"`	`"cumulative"`	Track-event attribution strategy
`batchSize`	`number`	`10`	Events per delivery batch before flushing
`flushIntervalMs`	`number`	`30000`	Max time before flushing pending events
`eventMaxQueueSize`	`number`	`1000`	Max events buffered before the oldest is dropped
`configTimeoutMs`	`number`	`10000`	Timeout for the config-bundle fetch
`eventsTimeoutMs`	`number`	`10000`	Timeout for event-delivery POSTs
`resolveTimeoutMs`	`number`	`5000`	Timeout for server-mode resolve calls (`POST /v1/resolve`)
`exposureSessionTtlMs`	`number`	`1800000`	Exposure-dedup session TTL (30 min)
`trackDecisions`	`boolean`	`true`	Emit decision events alongside exposure events
`decisionDeduplicationTtlMs`	`number`	`3600000`	Window in which the same unit + assignment won’t re-emit a decision event
`disableCloudEvents`	`boolean`	`false`	Stop sending events to Traffical (config is still fetched)
`disableAutoStableId`	`boolean`	`false`	Disable auto-generation of `stableId`
`storage`	`StorageProvider`	`LocalStorageProvider`	Persistence for the stable ID
`assignmentLogger`	`AssignmentLogger`	—	Route assignment rows to your own warehouse pipeline
`plugins`	`TrafficalPlugin[]`	`[]`	Plugins (DOM bindings, redirect tests, devtools)

Deprecated option aliases. Earlier releases used eventBatchSize, eventFlushIntervalMs, and a single requestTimeoutMs. These still work and forward to the canonical names above (batchSize, flushIntervalMs, and the three-way timeout split). requestTimeoutMs is honored as the legacy fallback for any of configTimeoutMs / eventsTimeoutMs / resolveTimeoutMs that you don’t set explicitly. Prefer the canonical names — the aliases will be removed in a future major.

Bundle caching

The browser SDK caches the bundle in memory. The first page load fetches it; subsequent loads benefit from HTTP caching at the CDN edge (Cache-Control: public, max-age=60, must-revalidate with ETag). On warm loads, resolution is available immediately.

Plugins

The browser SDK has a small plugin system that powers some of Traffical’s other tools:

Plugin	Purpose
DOM bindings	Auto-apply parameter values to DOM elements (used by the visual editor)
Redirect tests	URL split-testing — redirect users to different URLs based on assignment
Auto attributes	Add browser, page, UTM, and locale attributes to every decision context — see below
Warehouse-native logger	Forward assignment events to your warehouse
DevTools	Live SDK inspection in the browser (used by the DevTools bookmarklet)

import { createTrafficalClient, createDOMBindingPlugin } from "@traffical/js-client";

const traffical = await createTrafficalClient({
  orgId, projectId, env, apiKey,
  plugins: [createDOMBindingPlugin()],
});

Auto attributes

The auto-attributes plugin derives browser, page, UTM, and locale keys and adds them to every decision context. It is opt-in — nothing changes in the context you send until you register it. All keys live in the reserved $ namespace, so they never collide with your own, and they are registered as system attributes in every project, ready to target from the condition editor.

import { createTrafficalClient, autoAttributesPlugin } from "@traffical/js-client";

const traffical = await createTrafficalClient({
  orgId, projectId, env, apiKey,
  plugins: [autoAttributesPlugin()],
});

Via the CDN build: Traffical.autoAttributesPlugin() (Traffical.createAutoAttributesPlugin is an alias).

Key	Type	Value
`$browser`	enum	`chrome`, `edge`, `firefox`, `safari`, `other` — user-agent class only, no versions
`$os`	enum	`ios`, `android`, `macos`, `windows`, `linux`, `other` — user-agent class; iPadOS desktop user agents are detected via touch points
`$device_type`	enum	`mobile`, `tablet`, `desktop` — user-agent class first; desktop-class user agents with a coarse pointer fall back to viewport width (`< 768` mobile, `< 1024` tablet)
`$url`	string (url)	`location.href`
`$host`	string	`location.host`
`$path`	string	`location.pathname`
`$query`	string	`location.search` without the leading `?`; omitted when empty
`$referrer`	string	`document.referrer`; omitted when empty
`$page_title`	string	`document.title`; omitted when empty
`$utm_source`, `$utm_medium`, `$utm_campaign`, `$utm_term`, `$utm_content`	string	From the query string; persisted in `sessionStorage` (`traffical:utm`) and re-read on later pages of the session whose URL has none
`$locale`	string	`navigator.language` (BCP 47, e.g. `en-GB`)
`$timezone`	string	`Intl.DateTimeFormat().resolvedOptions().timeZone` (IANA, e.g. `Europe/Berlin`)

Rules:

Caller wins. Context you pass to decide() / getParams() overrides any derived key of the same name.
Nothing empty. A key that cannot be derived is omitted, never sent as "".
Re-derived on every decision, so single-page-app navigation is covered without patching history.
SSR-safe. Without a window the context passes through untouched.

autoAttributesPlugin({
  include?: AutoAttributeKey[],  // only derive these keys (default: all)
  exclude?: AutoAttributeKey[],  // never derive these keys (applied after include)
  persistUtm?: boolean,          // default true — sessionStorage-backed UTM persistence
});

AUTO_ATTRIBUTE_KEYS (the full key list) and the AutoAttributeKey type are exported for building include / exclude lists. The mobile SDKs emit the same $ keys from their device-info providers — see iOS and React Native.

Framework SDKs

If you’re using React or Svelte, use the framework-specific SDKs instead:

@traffical/react — provider and useTraffical hook
@traffical/svelte — stores and context API

Both wrap @traffical/js-client and expose the same plugin system.

Overview

Server SDKs

Client SDKs

Integrations

Patterns

Installation

Setup

Resolving parameters

Anonymous users and `identify`

Tracking events

Lifecycle

Options

Bundle caching

Plugins

Auto attributes

Framework SDKs

​Installation

​Setup

​Resolving parameters

​Anonymous users and identify

​Tracking events

​Lifecycle

​Options

​Bundle caching

​Plugins

​Auto attributes

​Framework SDKs

Installation

Setup

Resolving parameters

Anonymous users and `identify`

Tracking events

Lifecycle

Options

Bundle caching

Plugins

Auto attributes

Framework SDKs