> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traffical.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the Node.js SDK, resolve your first parameter, and track an event in under five minutes.

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](/concepts/projects-and-environments) created in the [dashboard](https://app.traffical.io)
* 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+

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @traffical/node
      ```

      ```bash pnpm theme={null}
      pnpm add @traffical/node
      ```

      ```bash yarn theme={null}
      yarn add @traffical/node
      ```

      ```bash bun theme={null}
      bun add @traffical/node
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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.
  </Step>

  <Step title="Resolve a parameter">
    Call `getParams` with user context and default values. Resolution is fully local — no API call is made.

    ```typescript theme={null}
    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.
  </Step>

  <Step title="Track an event">
    Send a track event when a user does something you want to measure. Events are batched in the background.

    ```typescript theme={null}
    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.
  </Step>
</Steps>

## Full example

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="How it works" icon="gears" href="/how-it-works">
    Local resolution, evaluation modes, and the config bundle.
  </Card>

  <Card title="Parameters" icon="sliders" href="/concepts/parameters">
    Typed values with defaults.
  </Card>

  <Card title="Projects & environments" icon="folder-tree" href="/concepts/projects-and-environments">
    What `orgId`, `projectId`, and `env` refer to.
  </Card>

  <Card title="Your first experiment" icon="rocket" href="/guides/first-experiment">
    The full loop — CLI, policy, SDK, results — in twenty minutes.
  </Card>
</CardGroup>