Installation

Install the CADENCE SDK in your project and configure it for your framework.

Supported platforms

  • Vanilla JavaScript (npm or CDN)
  • React (Vite, Create React App)
  • Next.js (App Router and Pages Router)
  • Node.js (server-side)

Install

bash
# npm
npm install @cadence/sdk

# yarn
yarn add @cadence/sdk

# pnpm
pnpm add @cadence/sdk

Or use the CDN with no build step (recommended for non-bundled sites):

html
<script src="https://cdn.softpath.co/sdk/v1/cadence.min.js"></script>
<script>
  Cadence.init({
    apiKey: 'YOUR_API_KEY',
    userId: '{{user.id}}' // Replace with your user ID
  });
</script>

See Script Tag Setup for the full guide.

Getting your API key

  1. Log in to the CADENCE dashboard
  2. Navigate to your workspace
  3. Select your project and go to Settings
  4. Copy the API key

Your API key is always visible in project settings. If you need to rotate it, click Regenerate Key — this invalidates the old key immediately.

Verifying installation

After adding the SDK to your site, go to your project Settings page and click Test Connection. You should see:

  • Connected — SDK loaded and API key is valid
  • Invalid Key — Check that the API key matches your project
  • Connection Error — Check browser console for errors

Framework setup

javascript
import { CadenceClient } from '@cadence/sdk'

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

async function main() {
  await cadence.ready()
  const variant = cadence.getVariant('my-experiment')
  console.log('Assigned variant:', variant)
}

main()

No environment variable prefix needed. If you're using a bundler, you can store the key however your build tool supports it.

CDN alternative (no build step):

html
<script src="https://cdn.softpath.co/sdk/v1/cadence.min.js"></script>
<script>
  Cadence.init({ apiKey: 'your_api_key_here' });

  Cadence.ready().then(function() {
    var variant = Cadence.getVariant('my-experiment');
    console.log('Assigned variant:', variant);
  });
</script>

The CDN version uses Cadence.init() instead of new CadenceClient(). See Script Tag Setup for more details.

Configuration options

The CadenceClient constructor accepts:

| Option | Type | Default | Description | |--------|------|---------|-------------| | sdkKey | string | required | Your project's SDK key | | userId | string | auto-generated | Unique user identifier. If not provided, generates and persists one in localStorage | | apiUrl | string | current origin | Base URL for the CADENCE API | | attributes | Record<string, unknown> | {} | User attributes for targeting |

typescript
const cadence = new CadenceClient({
  sdkKey: 'your_sdk_key',
  userId: currentUser.id,
  apiUrl: 'https://your-cadence-instance.com',
  attributes: {
    plan: 'pro',
    country: 'US',
  },
})

User identification

Use your own user IDs

For the most consistent experience, pass your application's user ID to the SDK. This ensures the same user always sees the same variant, even across devices or after clearing localStorage.

If you don't provide a userId, the SDK auto-generates one and stores it in localStorage under the key cadence_user_id. This works well for anonymous users but means:

  • The user gets a new identity in incognito mode
  • The user gets a new identity if localStorage is cleared
  • The user gets different identities across devices

For logged-in users, always pass your own user ID:

typescript
const cadence = new CadenceClient({
  sdkKey: process.env.NEXT_PUBLIC_CADENCE_SDK_KEY!,
  userId: session.user.id,
})

Anti-flicker

If you're using visual mutations (CSS/HTML changes via the Visual Editor), you may see a flash of the original content before the variant loads. Use enableAntiFlicker() to prevent this:

typescript
cadence.enableAntiFlicker(2000) // Hide content for up to 2 seconds
await cadence.ready()
cadence.getVariant('my-visual-test') // Content becomes visible after mutations apply

The page content is hidden until either:

  • Visual mutations are applied, or
  • The safety timeout (2 seconds) elapses

TypeScript

The SDK is written in TypeScript and includes type definitions. No additional @types packages needed.

typescript
import { CadenceClient } from '@cadence/sdk'

const cadence = new CadenceClient({ sdkKey: '...' })
await cadence.ready()

const variant: string = cadence.getVariant('my-experiment')
const enabled: boolean = cadence.isFeatureEnabled('my-feature')

Next steps