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_sk_...",
});

Use an SDK key (traffical_sk_..., scopes sdk:read+sdk:write) in browser code. SDK keys can fetch the bundle and send events but cannot modify configuration — safe to ship in client bundles.

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 experiments often need 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, exposures 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 variant while anonymous may see the control variant 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, do the experiment 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	SDK key (`traffical_sk_...`, scopes `sdk:read`+`sdk:write`) — browser-safe
`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 exposures
`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
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()],
});

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

Framework SDKs

​Installation

​Setup

​Resolving parameters

​Anonymous users and identify

​Tracking events

​Lifecycle

​Options

​Bundle caching

​Plugins

​Framework SDKs

Installation

Setup

Resolving parameters

Anonymous users and `identify`

Tracking events

Lifecycle

Options

Bundle caching

Plugins

Framework SDKs