Traffical

Traffical is a parameter-first experimentation and optimization platform. It unifies feature flags, A/B testing, and contextual bandits into a single system. SDKs resolve parameters locally at the edge — no per-request API calls, sub-millisecond latency, works offline.

Mental Model

Traffical is parameter-first. You define parameters with defaults, and Traffical handles the rest.

┌─────────────────────────────────────────────────────────────────────┐
│  Your Code                                                          │
│                                                                     │
│  1. Define parameters with defaults                                 │
│  2. Use the resolved values                                         │
│  3. Track events on conversion                                      │
└─────────────────────────────────────────────────────────────────────┘
                              ▲
                              │  (hidden from you)
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Traffical                                                          │
│                                                                     │
│  • Layers & policies for mutual exclusivity                         │
│  • Bucket assignment & deterministic hashing                        │
│  • Thompson Sampling & contextual bandits                           │
│  • Statistical analysis & optimization                              │
└─────────────────────────────────────────────────────────────────────┘

Key insights:

1. Parameters, Not Experiments — You define parameters with defaults. Experiments, feature flags, and optimizations are policies that control parameter assignment. Your code doesn’t need to know which.
2. Resolution Is Local — The SDK fetches a config bundle once and caches it. Every resolution call is synchronous from cache — no network latency, no render flicker.
3. Track Events for Learning — Call track() when valuable actions happen (purchase, signup, etc.). Traffical uses this data for adaptive optimization.

When to Use Traffical

Getting Started in a Project

Check for existing setup

Look for a .traffical/ directory or traffical.yaml in the project root. If it exists, the project is already initialized — check the config for existing parameters before creating new ones.

Initialize with the CLI

If no .traffical/ directory exists, initialize Traffical:

# Install the CLI
npm install -g @traffical/cli

# Initialize (creates .traffical/ directory with config and templates)
npx @traffical/cli init --api-key <api-key>

This creates:

.traffical/
├── config.yaml      # Parameter and event definitions
├── AGENTS.md        # AI agent integration guide (project-specific)
└── templates/       # Framework-specific code templates

The CLI auto-detects your framework (React, Next.js, Svelte, SvelteKit, Vue, Nuxt, Node.js) and generates appropriate templates.

Install an SDK

# Pick the one matching your framework
npm install @traffical/react
# or
npm install @traffical/svelte
# or
npm install @traffical/node

SDK Usage

React / Next.js

Provider setup (wrap your app once):

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

function App() {
  return (
    <TrafficalProvider
      config={{
        projectId: "proj_xxx",
        apiKey: "pk_live_your_public_key",
      }}
      context={{ userId: currentUser.id }}
    >
      <MyApp />
    </TrafficalProvider>
  );
}

Use in components:

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("checkout_click")}
    >
      {params["checkout.button.label"]}
    </button>
  );
}

Svelte / SvelteKit

Layout setup:

<!-- src/routes/+layout.svelte -->
<script>
  import { setTrafficalContext } from "@traffical/svelte";

  setTrafficalContext({
    projectId: "proj_xxx",
    apiKey: "pk_live_your_public_key",
    context: { userId: data.user?.id ?? "anonymous" },
  });
</script>

<slot />

Use in components (params and track are Svelte stores — use $ prefix):

<script>
  import { getTraffical } from "@traffical/svelte";

  const { params, track } = getTraffical({
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.button.label": "Buy now",
    },
  });
</script>

<button
  style="background-color: {$params['checkout.button.color']}"
  on:click={() => $track("checkout_click")}
>
  {$params["checkout.button.label"]}
</button>

Node.js (Server-side)

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

const traffical = await createTrafficalClient({
  projectId: "proj_xxx",
  apiKey: "sk_live_your_api_key",
});

// Resolve parameters (synchronous, from cached bundle)
const params = traffical.getParams({
  context: { userId: "user_789", locale: "en-US" },
  defaults: {
    "checkout.button.color": "#1E6EFB",
    "pricing.discount_pct": 0,
  },
});

// Track events
traffical.track("purchase", {
  context: { userId: "user_789" },
  value: 49.99,
});

Config-as-Code

Parameters and events are defined in .traffical/config.yaml (or traffical.yaml). This file is the source of truth — version-control it alongside your code.

version: "1.0"
project:
  id: proj_xxx
  orgId: org_xxx

parameters:
  checkout.button.color:
    type: string
    default: "#1E6EFB"
    description: Primary CTA button color

  checkout.show_trust_badges:
    type: boolean
    default: false

  pricing.discount_pct:
    type: number
    default: 0

events:
  purchase:
    valueType: currency
    unit: USD
    description: User completes a purchase

  add_to_cart:
    valueType: count
    description: User adds item to cart

Parameter types

Event value types

CLI Commands

# Check sync status between local config and Traffical platform
traffical status

# Push local changes to Traffical (local wins)
traffical push

# Pull remote changes to local config (remote wins)
traffical pull

# Bidirectional sync (local wins for conflicts)
traffical sync

# Import dashboard parameters (supports wildcards)
traffical import "ui.*"

# Validate config without pushing (dry run)
traffical push --dry-run

# Add Traffical references to AI tool config files
traffical integrate-ai-tools

Parameter Naming Conventions

Use dot notation: category.subcategory.name

Best Practices

1. Check existing parameters first — Look in .traffical/config.yaml (or traffical.yaml) before creating new ones. Reuse existing parameters where possible.

2. Always provide defaults — Defaults are used when no experiment is running, during SSR, and as fallback values. Your app should always work with just the defaults.

3. Track events at conversion points — Call track() on purchases, signups, and other valuable actions. This enables adaptive optimization.

4. Group related parameters — Keep correlated params in one useTraffical() / getTraffical() / getParams() call for proper attribution.

5. Use meaningful param names — Follow dot notation: category.subcategory.name. Be descriptive.

6. Define parameters in config — Add new parameters to .traffical/config.yaml and run traffical push to sync them. This keeps the config file as the source of truth.

7. Use the CLI for changes — Prefer traffical push / traffical pull / traffical sync over manual dashboard edits to avoid drift.

What You Don’t Need to Know

These are internal concepts handled by Traffical automatically:

• Layers, policies, allocations — Experiment infrastructure is managed in the dashboard
• Bucket assignment and hashing — Deterministic user assignment happens automatically
• Whether an A/B test vs. optimization is running — Your code is the same either way
• Statistical significance calculations — Traffical handles analysis in the background
• Decision deduplication — Multiple resolution calls are handled efficiently

Just parametrize your app, track conversions, and let Traffical handle the rest.

Documentation

• Quickstart: https://docs.traffical.io/quickstart
• How It Works: https://docs.traffical.io/how-it-works
• Parameters: https://docs.traffical.io/concepts/parameters
• React SDK: https://docs.traffical.io/sdks/react
• Svelte SDK: https://docs.traffical.io/sdks/svelte
• Node.js SDK: https://docs.traffical.io/sdks/node
• CLI: https://docs.traffical.io/tools/cli
• API Overview: https://docs.traffical.io/api/overview
• Dashboard: https://app.traffical.io