Getting Started with Algorithmic Testing in 5 Minutes

What You'll Build

By the end of this tutorial, you'll have a working integration that:

1. Requests the optimal headline variant for each visitor
2. Displays the assigned variant
3. Tracks conversions when visitors take action
4. Feeds results back to the algorithm so it learns

The entire integration takes about 20 lines of code.

Prerequisites

• A Bandit account with an API key (grab one from the dashboard)
• A JavaScript or TypeScript project (React, Next.js, Vue, plain JS all work)
• An active experiment with at least two treatments configured

Step-by-Step

Follow along with the interactive playground below. Each step shows the exact code you'll need.

pnpm add @runbandit/sdk

import { BanditClient } from '@runbandit/sdk'

const bandit = new BanditClient({
  apiUrl: 'https://runbandit.com',
  apiKey: 'your-api-key'
})

const assignment = await bandit.getAssignment(
  'experiment-headline',
  'user-123',
  { deviceType: 'mobile', location: 'US' }
)

// Use the assigned variant
document.querySelector('#headline').textContent =
  assignment.config.content

bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CONVERSION',
  value: 29.99,
  metadata: { product: 'premium-plan' }
})

Detailed Walkthrough

Step 1: Install

The SDK is a lightweight package with zero dependencies. It works in browsers and Node.js.

pnpm add @runbandit/sdk

Step 2: Initialize

Create a client instance with your API URL and key. You'll typically do this once at app startup.

import { BanditClient } from '@runbandit/sdk'

const bandit = new BanditClient({
  apiUrl: 'https://runbandit.com',
  apiKey: 'bnd_live_abc123'
})

The client handles batching, retries, and connection management internally. You don't need to worry about network details.

Step 3: Get an Assignment

When a user visits a page with an experiment, request an assignment. The algorithm selects the best-performing variant based on accumulated data.

const assignment = await bandit.getAssignment(
  'experiment-headline',  // your experiment ID
  'user-123'              // unique user identifier
)

The response includes:

• assignmentId: unique ID for this specific assignment (use for tracking)
• treatmentId: which variant was selected
• config: the variant's configuration object (content, colors, etc.)

Step 4: Display the Variant

Use the config object to render the assigned treatment. The structure depends on how you configured your treatments in the dashboard.

document.querySelector('#headline').textContent =
  assignment.config.content

// Or in React:
// <h1>{assignment.config.content}</h1>

Step 5: Track Conversions

When the user converts (clicks, purchases, signs up), report it back so the algorithm can learn.

bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CONVERSION',
  value: 29.99  // optional: revenue amount
})

Adding Context (Optional)

For contextual bandit algorithms, you can pass user context to get personalized assignments:

const assignment = await bandit.getAssignment(
  'experiment-headline',
  'user-123',
  {
    deviceType: 'mobile',
    location: 'US',
    timeOfDay: 'evening'
  }
)

The contextual algorithm uses these features to automatically learn which variants work best for different user segments.

Best Practices

Store the assignmentId. If conversions happen later (e.g., a purchase after browsing), persist the assignmentId in localStorage or your session store.

The SDK already batches events and sends them efficiently, so there's no need to call flush() after every event; let auto-batching do its job.

Clean up on unmount. In SPAs, call bandit.destroy() when the component unmounts to stop timers and flush remaining events.

Stick to one client instance: create the BanditClient once and reuse it rather than instantiating a new one per request.

What Happens Next

Once events flow in, the algorithm starts learning. Within a few hundred assignments, you'll see traffic automatically shift toward your best-performing variants. Monitor progress in the dashboard, where real-time charts show conversion rates and traffic allocation per variant.

No manual intervention required. The algorithm handles exploration and exploitation automatically.