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:

All four run methods — runExperience, runExperiences, runFeature and runFeatures in @convertcom/js-sdk — forward the object you pass to the bucketing engine whole, so no field is dropped on the way in; the rows above marked "Feature methods only" are simply the ones nothing on the experience path consumes. Three values are resolved by the Context after that forwarding and therefore take precedence over what you pass:

• visitorProperties is deep-merged over the properties given at context creation (and over the visitor's stored segments) rather than replacing them, so the engine receives the merged object.
• environment falls back to the context's own environment whenever you omit it.
• A preview context forces enableTracking: false, enableStorage: false and suppressEvents: true. While a preview is active these three cannot be re-enabled per call — the preview values are applied last and win.

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