Quickstart

Get your first A/B test running in 5 minutes. By the end of this guide, you'll have a working button color test with conversion tracking.

Prerequisites

A CADENCE account (sign up free)
A project with an SDK key (created during onboarding)

1. Install and initialize

Pick your stack to see the setup code:

Install the SDK:

bash

npm install @cadence/sdk

Initialize and run your first test:

javascript

import { CadenceClient } from '@cadence/sdk'

const cadence = new CadenceClient({
  sdkKey: 'YOUR_SDK_KEY',
})

async function main() {
  await cadence.ready()

  const variant = cadence.getVariant('button-color-test')
  const button = document.querySelector('#cta-button')

  if (variant === 'blue-button') {
    button.style.backgroundColor = '#3b82f6'
    button.textContent = 'Get Started Free'
  }

  button.addEventListener('click', () => {
    cadence.trackConversion('signup-click')
  })
}

main()

Keep your SDK key safe

Your SDK key is included in client-side code and is visible to users. It only grants read access to your experiment configuration and write access to events. Never expose your Supabase service role key.

2. Create your test in the dashboard

Go to your project in the CADENCE dashboard
Click New Experiment
Name it button-color-test (must match the string in your code)
Add two variants:
- control — your existing button
- blue-button — the new blue button
Set traffic allocation to 100% and split weights 50/50
Start the experiment

3. Track conversions

When a user completes the action you're measuring, call trackConversion():

typescript

cadence.trackConversion('signup-click')

The SDK automatically:

Assigns the same variant to the same user every time (deterministic hashing)
Tracks an exposure event when getVariant() is called
Batches events for efficient delivery (every 5 seconds or 10 events)
Flushes remaining events on page unload

4. View results

Go to your experiment in the CADENCE dashboard. You'll see:

Conversion rate per variant
Statistical significance (p-value)
Lift percentage — how much better the treatment is vs. control
Confidence intervals — the range of likely true effect sizes

Wait for significance

Don't stop your test early. Wait until you reach statistical significance (p < 0.05) AND have at least 100 conversions per variant. Stopping too early leads to false positives.

What's next

Installation — Framework-specific setup details
API Reference — Every method documented
Creating Tests — Advanced patterns like multi-variant tests
Visual Editor — Make visual changes without code

Common issues

Variant always returns "control"

Make sure you called await cadence.ready() before getVariant(). Without it, the SDK hasn't loaded your experiment configuration yet.

Events not showing up

Events are batched and sent every 5 seconds. Wait a moment, then refresh the dashboard. Also check your browser's network tab for failed requests to /api/sdk/[key]/events.

Same user gets different variants

This happens when the userId changes between sessions. By default, the SDK generates and persists a userId in localStorage. If you clear localStorage or use incognito mode, the user gets a new identity. See Troubleshooting for more.