Skip to main content
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 project settings
  • Node.js 18+
1

Install the SDK

npm install @traffical/node
2

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

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

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 optimization engine 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.

CLI

Manage parameters as code.