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({
  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.

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	Default	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	`false`	Whether to permanently update in-memory visitor properties
`enableTracking`	boolean	`true`	Whether to track bucketing events immediately
`enableStorage`	boolean	`true`	Whether to persist the bucketing decision to the visitor store — the in-memory map and any configured DataStore. Set `false` for a decision that leaves nothing behind
`suppressEvents`	boolean	`false`	Suppress the `location.activated` / `location.deactivated` event fires only. Location and audience matching are unaffected, and this is independent of `enableTracking` and `enableStorage`
`ignoreLocationProperties`	boolean	`false`	Skip location matching for this call
`forceVariationId`	string	—	Force a specific variation instead of bucketing the visitor
`environment`	string	context value	Override the environment for this call
`typeCasting`	boolean	`true`	Feature methods only — auto-convert variable values to their defined type
`experienceKeys`	string[]	—	Feature methods only — limit evaluation to specific experiences. Honored by both `runFeature` and `runFeatures` from `@convertcom/js-sdk` 5.0.2; before that only `runFeature` applied it

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.

Next Steps

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