Setting up Contextual Bandits

​

Requirements at a glance

• An Enterprise plan — Contextual Bandits are an Enterprise-only beta feature.
• A supported SDK on a compatible version — currently JavaScript, React, Node.js, Python, Go, Kotlin (Android), and Swift (iOS) (see below).
• A connected Data Source with a warehouse the bandit can query, plus a dedicated Contextual Bandit Assignment Query that selects your user id, timestamp, and one or more context columns (see step 4).
• A Fact Metric to use as the Decision Metric — legacy (non-fact) metrics are not supported as decision metrics.

​

1. Install or upgrade to a compatible SDK

npm install --save @growthbook/growthbook
# React apps
npm install --save @growthbook/growthbook-react
# Python apps
pip install --upgrade growthbook
# Go apps
go get github.com/growthbook/growthbook-golang@latest

​

2. Check your SDK Connection

1. Language and version — make sure the connection’s SDK language is one of the languages listed above and its version is set to a compatible version. GrowthBook only includes contextual bandit definitions in the SDK payload for connections that support them.
2. Cache TTL — contextual bandits change variation weights while running. If your SDK caches the payload longer than the bandit’s update cadence, users will be bucketed with stale weights, which slows learning and can trigger SRM warnings. Make sure your SDK’s maxAge / TTL settings refresh the payload significantly more often than the bandit reweights (or use streaming updates). The cache max-age recommendations for multi-armed bandits apply here too.

​

3. Update your tracking callback

const gb = new GrowthBook({
  apiHost: "https://cdn.growthbook.io",
  clientKey: "sdk-abc123",
  trackingCallback: (experiment, result, user) => {
    analytics.track("Experiment Viewed", {
      experimentId: experiment.key,
      variationId: result.key,
      // Directly pass through attributes used for contextual bandits (e.g. userRole)
      deviceId: user.attributes.deviceId,
      userRole: user.attributes.userRole,
      // Contextual bandit fields (undefined for regular experiments)
      leafId: result.leafId,
      banditVersion: result.banditVersion,
      variationWeights: result.variationWeights,
    });
  },
});

​

4. Create a Contextual Bandit Assignment Query

SELECT
  device_id,
  timestamp,
  experiment_id,
  variation_id,
  -- Context columns that match the new trackingCallback attribute
  -- columns you're using for personalization, e.g. userRole
  userRole,
  -- Optional contextual bandit health-check columns, logged by your tracking callback
  leaf_id,
  bandit_version,
  variation_weights
FROM contextual_bandit_events

• At least one context column (e.g. userRole) is required — a bandit with no context to split on is just a multi-armed bandit. It should ideally match the columns you’re sending from the user argument from your tracking callback. The set passed here must match your SDK Attributes in GrowthBook in order to be used to target the contextual bandit.
• leaf_id, bandit_version, and variation_weights are the warehouse-side counterparts of the tracking callback fields from step 3. They are optional, but you should include them — later versions of contextual bandits will use them for health checks like SRM.

​

5. Create the Contextual Bandit

• A hash attribute — the attribute used to randomize users into variations, which should map to the user identifier in your assignment query. For short-lived bandits, we suggest a session_id or device_id that will re-generate on future visits to ensure you get the most power while managing when a session ends yourself.
• A Contextual Bandit Assignment Query — the query you created in step 4. The attribute columns you pass there will dictate the attributes that will be used to target the contextual bandit. Future versions of contextual bandits will let you select a subset of these columns to use as targeting attributes.
• Exploration window and update cadence — how long the bandit collects data before it starts reweighting, and how often it reweights after that. See the bandit configuration guide for guidance.
• A Decision Metric — the single Fact Metric the bandit optimizes toward. The same guidance as for multi-armed bandits applies: prefer a metric with a short conversion window and a conversion rate that isn’t extremely low or high.

​

6. Link a Feature Flag and start

1. Create (or pick) a feature flag and link it from the bandit’s page. This adds a contextual bandit rule to the flag in a draft revision.
2. Define the value each bandit variation should serve.
3. Start the bandit. Pending drafts on linked flags are published automatically when the bandit starts.

• Creating a feature flag via the postFeatureV2 endpoint.
• Linking the feature flag to the contextual bandit via the addContextualBanditLinkedFeature endpoint.
• Starting the contextual bandit via the startContextualBandit endpoint.

​

Next steps

• Driving a Contextual Bandit via API — run the same lifecycle entirely from the REST API, including refreshing and reading results.
• Contextual Bandits overview — concepts, and when to use one over a multi-armed bandit.
• Contextual Bandit technical details — how per-context weights are computed.