The SDK can be initialized in two ways: using an SDK Key (recommended) or by providing a static configuration object.

The SDK fetches the project configuration from Convert's CDN and refreshes it at the configured interval.

import type {ConvertInterface, ConvertConfig} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx',
  sdkKeySecret: 'xxx', // required when using an authenticated SDK key
  dataRefreshInterval: 300000, // in milliseconds (5 minutes)
  environment: 'staging' // or "production"
} as ConvertConfig);

convertSDK.onReady().then(() => {
  // SDK is ready - create user context and run experiences
});

onReady() returns a Promise that resolves when the SDK has successfully fetched the initial configuration data and is set up. Always wait for this before calling any SDK methods.

convert.onReady().then(() => {
  console.log('Convert SDK is ready!');
  // Now you can start creating contexts for visitors
}).catch(error => {
  console.error('Error initializing Convert SDK:', error);
});

Provide a project configuration object directly. The config data can be fetched from https://cdn-4.convertexperiments.com/api/v1/config/{account_id}/{project_id}.

import type {ConvertInterface, ConvertConfig} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const convertSDK: ConvertInterface = new ConvertSDK({
  data: { /* your static project configuration */ },
  environment: 'staging'
} as ConvertConfig);

convertSDK.onReady().then(() => {
  // SDK is ready immediately when using static config
});

When using static project data, the SDK is instantiated as soon as the instance is created and can be used right away.

Once initialized, create a Context tied to a specific visitor. A unique userId is required for deterministic bucketing.

import type {ContextInterface} from '@convertcom/js-sdk';

const userContext: ContextInterface = convertSDK.createContext(
  'user-unique-id',
  {
    country: 'US',
    language: 'en'
  }
);

As long as the userId and experience configuration remain the same, bucketing stays consistent. To ensure consistency even when configuration changes, provide a Persistent DataStore.

Every userContext method that runs experiences or features accepts an optional attributes object:

enableStorage and suppressEvents are what a preview context sets for you to leave zero trace; you rarely set them by hand. See QA & Preview.

• Configuration -- full SDK config options reference
• Code Examples -- complete examples for every SDK method