Initialization

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

Using SDK Key

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()` Promise

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);
});

Using Static Configuration

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({
  projectConfig: { /* 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.

Creating a User Context

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.

Attributes Object

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

Property	Type	Description
`locationProperties`	object	Key-value pairs used for evaluating experience locations
`visitorProperties`	object	Key-value pairs used for evaluating experience audiences (overwrites same keys from context creation)
`updateVisitorProperties`	boolean	Whether to permanently update in-memory visitor properties
`enableTracking`	boolean	Whether to track bucketing events immediately (default: `true`)
`environment`	string	Override environment for this call

Next Steps

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