Quickstart

This guide walks you through integrating Traffical into a Node.js application. By the end, you will resolve a parameter value and track an event.

Prerequisites

A Traffical account with a project created in the dashboard
An SDK key (traffical_sk_..., scopes sdk:read+sdk:write) from your organization’s API Keys page (in the sidebar when viewing your organization, or from the account menu)
Node.js 18+

Install the SDK

npm install @traffical/node

pnpm add @traffical/node

yarn add @traffical/node

bun add @traffical/node

Initialize the client

Create a client with your organization, project, environment, and an SDK key. The client fetches the config bundle from Traffical and caches it in memory.

import { createTrafficalClient } from "@traffical/node";

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

The await matters — the client fetches the initial bundle before it can resolve parameters. If you can’t await at startup, use createTrafficalClientSync and call waitUntilReady() later.

Resolve a parameter

Call getParams with user context and default values. Resolution is fully local — no API call is made.

const params = traffical.getParams({
  context: { userId: "user_789", locale: "en-US" },
  defaults: {
    "checkout.button.color": "#1E6EFB",
    "checkout.headline": "Complete your order",
  },
});

console.log(params["checkout.button.color"]); // "#1E6EFB" or experiment variant
console.log(params["checkout.headline"]);     // "Complete your order" or variant

The context object is used for two things:

Bucketing — the unit key (typically userId) determines which allocation the user gets, and the assignment is stable across requests.
Targeting — other fields like locale, plan, or country are evaluated against policy conditions.

The defaults object is your safety net. The SDK returns these values when no policy matches, when the bundle hasn’t loaded yet, or when Traffical is unreachable.

Track an event

Send a track event when a user does something you want to measure. Events are batched in the background.

traffical.track("purchase", {
  unitKey: "user_789",
  properties: { order_total: 49.99, currency: "USD" },
});

If you’re running an adaptive policy, the optimizer uses these events as reward signals to learn which variants perform best.

Full example

import { createTrafficalClient } from "@traffical/node";

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

function handleCheckout(userId: string, orderTotal: number) {
  const params = traffical.getParams({
    context: { userId },
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.show_trust_badges": false,
    },
  });

  renderCheckout({
    buttonColor: params["checkout.button.color"],
    showTrustBadges: params["checkout.show_trust_badges"],
  });

  traffical.track("checkout_started", { unitKey: userId });
}

Next steps

How it works

Local resolution, evaluation modes, and the config bundle.

Parameters

Typed values with defaults.

Projects & environments

What orgId, projectId, and env refer to.

Your first experiment

The full loop — CLI, policy, SDK, results — in twenty minutes.

Getting started

Core concepts

Experimentation

Statistics

Guides

Dashboard

Governance

Warehouse connectors

Developer tools

Reference

Prerequisites

Full example

Next steps

How it works

Parameters

Projects & environments

Your first experiment

​Prerequisites

​Full example

​Next steps

How it works

Parameters

Projects & environments

Your first experiment

Prerequisites

Full example

Next steps