React SDK

@traffical/react provides a context provider and hooks for resolving parameters and tracking events in React apps. It wraps @traffical/js-client, so everything the browser client supports works here too.

Installation

npm install @traffical/react

pnpm add @traffical/react

yarn add @traffical/react

Setup

Wrap your app with TrafficalProvider:

import { TrafficalProvider } from "@traffical/react";

function App() {
  return (
    <TrafficalProvider
      config={{
        orgId: "org_acme",
        projectId: "proj_marketplace",
        env: "production",
        apiKey: process.env.NEXT_PUBLIC_TRAFFICAL_API_KEY!,
      }}
    >
      <MyApp />
    </TrafficalProvider>
  );
}

Use an publishable SDK key (traffical_pk_...) in client code — it is safe to ship in a client bundle.

The `useTraffical` hook

Use useTraffical in any component to resolve parameters and track events:

import { useTraffical } from "@traffical/react";

function CheckoutButton() {
  const { params, track } = useTraffical({
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.button.label": "Buy now",
    },
  });

  return (
    <button
      style={{ backgroundColor: params["checkout.button.color"] }}
      onClick={() => track("cta_click")}
    >
      {params["checkout.button.label"]}
    </button>
  );
}

Hook options

Option	Type	Description
`defaults`	`Record<string, ParameterValue>`	Default values for the parameters this component reads. Required.
`context`	`Context`	Optional extra context merged with provider context.
`tracking`	`"full" \| "decision" \| "none"`	Tracking mode (see below). Default `"full"`.

Hook return value

Field	Type	Description
`params`	`Record<string, ParameterValue>`	Resolved parameter values
`decision`	`DecisionResult \| null`	Full decision record (decisionId, layer assignments)
`ready`	`boolean`	`true` once the bundle has loaded at least once
`error`	`Error \| null`	Any non-fatal error from the last refresh
`track`	`(event, options?) => void`	Track an event
`trackExposure`	`() => void`	Manually emit an exposure event (for `"decision"` mode)
`flushEvents`	`() => Promise<void>`	Force flush of pending events

Tracking modes

useTraffical({ defaults, tracking: "full" });      // default — automatic decision + exposure events
useTraffical({ defaults, tracking: "decision" });  // automatic decision; you call trackExposure()
useTraffical({ defaults, tracking: "none" });      // no tracking (SSR, tests)

"decision" is useful when the treatment is below the fold — you want to record the decision but only record the exposure event once the user actually sees the change.

Setting context

Pass user context through the provider; it flows to all hooks:

<TrafficalProvider
  config={{
    orgId: "org_acme",
    projectId: "proj_marketplace",
    env: "production",
    apiKey: process.env.NEXT_PUBLIC_TRAFFICAL_API_KEY!,
    contextFn: () => ({
      userId: currentUser.id,
      locale: navigator.language,
      plan: currentUser.plan,
    }),
  }}
>
  <MyApp />
</TrafficalProvider>

Context is supplied via contextFn inside config — a function called on each resolution. When the values it returns change (e.g. after login), hooks re-resolve with the new values. To customize the unit key, pass unitKeyFn inside config as well.

Anonymous users and `identify`

The React SDK inherits the browser client’s stable-ID handling. Before the user logs in, the SDK uses an auto-generated stable ID. After login:

function Login() {
  const { client } = useTrafficalClient();

  function handleLogin(user) {
    client.identify(user.id);
    // assignments may change for this session
  }
}

SSR (Next.js, RSC)

For Next.js (App Router or Pages), fetch the bundle on the server and pass it to TrafficalProvider as localConfig. There is no @traffical/react/server entry point — fetch the config bundle directly from the SDK config endpoint (the same one the client SDK calls):

// app/layout.tsx (RSC)
import { TrafficalProvider } from "@traffical/react";

async function fetchBundle() {
  const res = await fetch(
    "https://sdk.traffical.io/v1/config/proj_marketplace?env=production",
    {
      headers: { Authorization: `Bearer ${process.env.TRAFFICAL_API_KEY!}` },
      next: { revalidate: 60 },   // cache via Next.js fetch integration
    },
  );
  return res.ok ? res.json() : null;
}

export default async function RootLayout({ children }) {
  const bundle = await fetchBundle();

  return (
    <TrafficalProvider config={{
      orgId: "org_acme",
      projectId: "proj_marketplace",
      env: "production",
      apiKey: process.env.NEXT_PUBLIC_TRAFFICAL_API_KEY!,
      localConfig: bundle,   // server + client resolve from the same bundle → no flash
    }}>
      {children}
    </TrafficalProvider>
  );
}

Use a publishable SDK key (traffical_pk_...) in the client provider and a server-side SDK key (traffical_sk_...) for the server-side bundle fetch, kept in a private environment variable. See the SSR patterns page for the full setup, including the Pages Router.

Standalone tracking

If you only need to track an event, use useTrafficalTrack:

import { useTrafficalTrack } from "@traffical/react";

function Footer() {
  const track = useTrafficalTrack();
  return <a href="#" onClick={() => track("newsletter_signup_clicked")}>Subscribe</a>;
}

Direct client access

If you need to do something the hooks don’t expose, get the underlying client. useTrafficalClient() returns { client, ready, error } — the client can be null until the provider has initialized, so guard it:

import { useTrafficalClient } from "@traffical/react";

function DebugPanel() {
  const { client, ready } = useTrafficalClient();
  return (
    <button disabled={!ready || !client} onClick={() => client?.flushEvents()}>
      Flush
    </button>
  );
}

Provider options

TrafficalProvider takes exactly two props: config and children. Everything else is a field of config (TrafficalProviderConfig):

`config` field	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
`localConfig`	`ConfigBundle`	—	Embedded bundle for cold-start / SSR hydration
`refreshIntervalMs`	`number`	`60000`	Bundle refresh interval
`unitKeyFn`	`() => string`	—	Custom unit-key resolution
`contextFn`	`() => Context`	—	Dynamic context — called on every resolution
`trackDecisions`	`boolean`	`true`	Emit decision events alongside exposure events
`plugins`	`Plugin[]`	—	SDK plugins

These are the same options as the browser SDK; pass them all inside config.

Next steps

SSR patterns

No FOOC, hydration with the same bundle.

Experimentation patterns

Patterns for web UI and SSR tests.

Overview

Server SDKs

Client SDKs

Integrations

Patterns

Installation

Setup

The `useTraffical` hook

Hook options

Hook return value

Tracking modes

Setting context

Anonymous users and `identify`

SSR (Next.js, RSC)

Standalone tracking

Direct client access

Provider options

Next steps

SSR patterns

Experimentation patterns

​Installation

​Setup

​The useTraffical hook

​Hook options

​Hook return value

​Tracking modes

​Setting context

​Anonymous users and identify

​SSR (Next.js, RSC)

​Standalone tracking

​Direct client access

​Provider options

​Next steps

SSR patterns

Experimentation patterns

Installation

Setup

The `useTraffical` hook

Hook options

Hook return value

Tracking modes

Setting context

Anonymous users and `identify`

SSR (Next.js, RSC)

Standalone tracking

Direct client access

Provider options

Next steps