Optimization

Adaptive policies go beyond static A/B tests. Instead of fixed allocations, the optimizer shifts traffic toward better-performing variants based on observed rewards — automatically, continuously, and without code changes.

When to use adaptive policies

Use adaptive policies when:

You want to minimise regret — the cost of showing the inferior variant longer than necessary.
The best variant may change over time (seasonality, mix shifts).
You want continuous optimization rather than a one-time decision.
You want personalized selection based on user context (contextual bandits).

Stick with static A/B tests when:

You need a clean point-in-time decision with an unambiguous winner for stakeholders.
The cost of the variant is large enough that you want a deliberate ramp afterwards (use rollouts).
Your goal metric is delayed or noisy (the engine will still work, but a static test gives you a more interpretable result).

Algorithms

Algorithm	What it does	Best for
`thompson_bernoulli`	Thompson Sampling. Bayesian exploration/exploitation — Beta-Bernoulli for conversion goals, Gaussian with measured variance for count/sum goals.	The default. Binary outcomes and per-user counts or values alike
`epsilon_greedy`	Mostly exploits the best-known variant; explores randomly with probability ε.	Simple baseline with predictable exploration rate
`ucb1`	Upper Confidence Bound. Optimistic exploration that naturally decreases over time; the bound scales with the measured spread of your rewards for count/sum goals.	A deterministic, parameter-free explorer — works with all goal types
`linear_contextual`	Personalized scoring per user via a trained linear model. Resolved locally.	Personalization — when the best variant depends on user context

Not sure which to pick — or how the goal event shapes what the optimizer learns? See Choosing an optimization algorithm.

Setting up an adaptive policy

Define the goal event in .traffical/config.yaml or in the dashboard:

events:
  purchase:
    valueType: currency
    unit: USD

Create the policy in the dashboard:
- Kind: adaptive
- Algorithm: thompson_bernoulli
- Goal event: purchase
- Goal type: conversion_rate
- Min exposures before shift: 100
- Window size: 60 minutes
Define allocations. Initial ranges can be uniform; the engine will adjust them.
Allocation Initial range Override
low_price 0–332 pricing.discount_pct: 5
mid_price 333–665 pricing.discount_pct: 10
high_price 666–999 pricing.discount_pct: 20

Allocation	Initial range	Override
`low_price`	`0–332`	`pricing.discount_pct: 5`
`mid_price`	`333–665`	`pricing.discount_pct: 10`
`high_price`	`666–999`	`pricing.discount_pct: 20`

Implement in code — same as a static policy:

const params = traffical.getParams({
  context: { userId: "user_789" },
  defaults: { "pricing.discount_pct": 0 },
});

applyDiscount(params["pricing.discount_pct"]);

traffical.track("purchase", { order_total: orderTotal }, { unitKey: "user_789" });

The SDK resolves from the bundle. The engine periodically retrains and republishes the bundle with updated bucket ranges. Your code never changes. As data accrues, the policy page tracks progress through four phases — exploring → learning → converging → converged. See What to expect while it runs for what each phase means and why “converged” still defers to measured significance.

Tuning knobs

Knob	What it does
`minExposuresBeforeShift`	The engine won’t change allocations until the policy has seen at least this many total exposures across all allocations. Prevents premature shifts on noisy early data.
`maxShiftPerUpdate`	Caps how much traffic can move in a single update (e.g. 0.1 = at most 10% of traffic shifts per cycle).
`windowSizeMinutes`	How often the engine re-evaluates. Shorter windows = faster reaction, but noisier.

Optimizing with your warehouse

The optimizer’s reward source is the policy’s primary metric — its warehouse aggregates feed the bandit on every tick. On projects with defined events, the goal event you pick simply resolves to that metric for you — and the goal step also lets you switch to picking a metric directly, so you can optimize any fact-backed metric even when native events exist. On BYO-warehouse projects with no event definitions at all, the metric is the only way to declare the goal:

Define a fact over your own tables (SQL in your warehouse’s dialect) — one row per goal action, with the entity key, a timestamp, and an optional value column.
Create a metric on that fact — conversion, count, or sum. Ratio metrics can’t be optimization goals (the reward would use only the numerator).
Create the adaptive policy and pick that metric in the goal step. The goal type follows the metric’s type, and the metric is attached as the policy’s primary — the optimizer and measurement judge the same quantity by construction.

Two things to know about this contract:

The primary metric is authoritative. Re-pointing the policy’s primary metric re-points the optimizer on its next tick. A policy without a resolvable primary metric can’t start, and a running one reports a “no goal metric” health failure instead of silently optimizing nothing.
Metrics that should go down work too. A goal metric with a decrease desired direction (error rate, time-to-complete, support contacts) makes the bandit minimize: traffic shifts toward the variant with the lowest reward.

Adaptive policies also require the project to actually be served by Traffical. If yours is a measurement-only deployment — something else entirely decides who sees what, and Traffical purely analyzes — mark the project externally served in project settings: adaptive policies are then blocked from starting and the optimizer skips the project, since nothing would read the traffic splits it writes. Note that routing assignment data through your own pipeline (the BYO assignment logging pattern) is not external serving — the SDK still serves the traffic there, and adaptive optimization works end to end.

Contextual bandits

The linear_contextual algorithm personalizes selection: different users get different variants based on context features. The training pipeline learns coefficients per allocation per feature; those coefficients ship in the config bundle; the SDK uses them to score each allocation for the current user at resolution time.

What it looks like in code

The code is identical to any other adaptive policy — you just pass more context:

const params = traffical.getParams({
  context: {
    userId: "user_789",
    "user.engagement_score": user.engagementScore,
    "user.device_type": device.type,
    "user.days_since_signup": user.daysSinceSignup,
    "session.referrer": document.referrer,
  },
  defaults: {
    "homepage.layout": "standard",
  },
});

The model uses the listed context fields. Fields not in the model’s training set are ignored.

Scoring

For each allocation, the SDK computes:

score(allocation) = intercept(allocation) + Σ (coefficient(feature, allocation) × value(feature))

It then applies softmax with temperature gamma to convert scores into selection probabilities, and enforces a minimum probability per allocation (actionProbabilityFloor) so the model keeps exploring.

Setting	Meaning
`gamma`	Softmax temperature. Lower = more deterministic (exploits learned best); higher = more uniform (more exploration). Typical: 0.1–0.5.
`actionProbabilityFloor`	Minimum probability any allocation can have. Guarantees ongoing exploration. Typical: 0.05.
`defaultAllocationScore`	Score for cold-start (no learned coefficients yet).

Context logging allowlist

To train the model, the platform needs to see the context fields with each exposure event. To protect PII, only fields you explicitly allow-list are logged:

{
  "contextLogging": {
    "allowedFields": [
      "user.engagement_score",
      "user.device_type",
      "user.days_since_signup",
      "session.referrer"
    ]
  }
}

Anything outside the allowlist is dropped before storage.

Typing your context fields

A plain string entry lets the pipeline infer the field’s type from the data. You can also declare the type, which makes encoding predictable and guards against the classic foot-guns (a raw ID or timestamp entering the model unbounded). An allow-list entry can be an object:

{
  "contextLogging": {
    "allowedFields": [
      "session.referrer",
      { "key": "user.device_type", "type": "enum", "values": ["mobile", "desktop", "tablet"] },
      { "key": "user.engagement_score", "type": "number", "range": [0, 100] },
      { "key": "user.plan_tier", "type": "enum", "values": ["free", "pro", "enterprise"] },
      { "key": "session.started_at", "type": "timestamp" }
    ]
  }
}

Type	Encoding
`enum`	One-hot over the declared `values`; an unseen level folds into an `other` bucket (the feature space stays stable across retrains).
`string`	Top-K most frequent values + `other` (set `topK`, default 20).
`number`	Fed to the model directly; the trainer standardizes scale internally, so a 0–100 score sits comfortably next to 0/1 indicators. `range` and quantile `binning` are available for bounded or non-monotonic features.
`boolean`	0/1.
`timestamp`	Never used raw — expanded into day-of-week, time-of-day (four-hour buckets), and is-weekend features.

Declared fields are encoded deterministically regardless of the traffic window, and editing a declaration retrains the model from scratch on its next training run — the change doesn’t wait for a scheduled rebuild. Fields you leave as plain strings keep the inferred behaviour.

When to use contextual bandits

When the optimal variant differs per user, and you can describe “who they are” with a handful of features:

Homepage layout by engagement level and device type
CTA copy by referral source and purchase history
Recommendation style by user segment

The features should be available at decision time. Don’t include features derived from the outcome you’re trying to predict. One expectation to set: a contextual policy never converges on a single winner — winners vary per context — so the dashboard doesn’t show a single-winner runtime estimate for it. Measurement progress still tracks the evidence on the policy’s primary metric.

Per-entity bandits

For optimization at the entity level — each product, each merchant, each category learns independently — use a per-entity adaptive policy:

entityConfig:
  entityKeys: ["productId"]
  resolutionMode: "bundle"      # or "edge"

Each entity gets its own bandit. A product with 1000 views has its own learned weights; a product with 3 views falls back to the global prior. Every entity’s traffic split also keeps an exploration floor — each allocation retains at least a small share (1% by default) of that entity’s traffic — so no option is ever fully starved, even after an entity’s bandit has settled on a favorite.

Resolution modes

Mode	How it works	Latency	Freshness
`bundle`	Entity weights ship in the config bundle. SDK resolves locally.	Sub-ms	Bundle refresh cadence (typically hourly for per-entity policies)
`edge`	SDK calls Traffical for each decision. Returns the latest weights.	~50ms	Real-time

bundle is the right choice for high-traffic entities (product pages, search results). edge is for low-traffic, high-stakes entities where you need every decision to use the freshest possible weights.

Dynamic allocations

When each entity has a different number of options (e.g. each product has a different image count), use dynamicAllocations:

entityConfig:
  entityKeys: ["productId"]
  resolutionMode: "bundle"
  dynamicAllocations:
    countKey: "imageCount"

If context.imageCount = 5, the SDK creates five allocations on the fly and selects from them based on learned weights. The selected index is reported as the allocation name in the decision metadata.

Next steps

Per-entity adaptive pattern

Full walkthrough with metric setup.

Contextual bandit pattern

Personalized layouts and CTAs.

Warehouse-native

Training contextual bandits from warehouse data.

Getting started

Core concepts

Experimentation

Statistics

Guides

Dashboard

Governance

Warehouse connectors

Developer tools

Reference

When to use adaptive policies

Algorithms

Setting up an adaptive policy

Tuning knobs

Optimizing with your warehouse

Contextual bandits

What it looks like in code

Scoring

Context logging allowlist

Typing your context fields

When to use contextual bandits

Per-entity bandits

Resolution modes

Dynamic allocations

Next steps

Per-entity adaptive pattern

Contextual bandit pattern

Warehouse-native

​When to use adaptive policies

​Algorithms

​Setting up an adaptive policy

​Tuning knobs

​Optimizing with your warehouse

​Contextual bandits

​What it looks like in code

​Scoring

​Context logging allowlist

​Typing your context fields

​When to use contextual bandits

​Per-entity bandits

​Resolution modes

​Dynamic allocations

​Next steps

Per-entity adaptive pattern

Contextual bandit pattern

Warehouse-native

When to use adaptive policies

Algorithms

Setting up an adaptive policy

Tuning knobs

Optimizing with your warehouse

Contextual bandits

What it looks like in code

Scoring

Context logging allowlist

Typing your context fields

When to use contextual bandits

Per-entity bandits

Resolution modes

Dynamic allocations

Next steps