Skip to content

CodeExamples

Jump to bottom
Ahmed Abbas edited this page Apr 7, 2026 · 1 revision

JavaScript SDK — Code Examples

Complete code examples for all SDK methods. All examples are extracted from the official SDK documentation.

Running Experiences

Run All Active Experiences

Loops through each active experience, evaluates targeting rules, and returns the selected variation for each.

const variations: BucketedVariation[] = userContext.runExperiences();

// With attributes:
const variations: BucketedVariation[] = userContext.runExperiences({
  locationProperties: { url: '/pricing' },
  visitorProperties: { plan: 'pro' },
  enableTracking: true
});

Parameters:

Parameter Type Required Description
attributes object No See Attributes Object

Returns: Array<BucketedVariation>

Full Example

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

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variations: BucketedVariation[] = context.runExperiences();
  console.log(variations);
});

Run a Single Experience

Evaluates a single experience by its key.

const variation: BucketedVariation = userContext.runExperience('experience-key');

// With attributes:
const variation: BucketedVariation = userContext.runExperience('experience-key', {
  locationProperties: { url: '/' },
  visitorProperties: { country: 'US' }
});

Parameters:

Parameter Type Required Description
experienceKey string Yes The experience's unique key
attributes object No See Attributes Object

Returns: BucketedVariation (see Data Model > BucketedVariation)

Full Example

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

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx'
} as ConvertConfig);

convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variation: BucketedVariation = context.runExperience('experience-key');
  console.log(variation);
});

Running Features

Features are resolved through variations of relevant experiences. See Data Model > How Features Are Resolved for the full resolution chain.

Run All Features

Returns all features with their status and variable values for the visitor.

const features: BucketedFeature[] = userContext.runFeatures();

// With attributes:
const features: BucketedFeature[] = userContext.runFeatures({
  locationProperties: { url: '/dashboard' },
  visitorProperties: { tier: 'premium' },
  typeCasting: true
});

Parameters:

Parameter Type Required Description
attributes object No See Attributes Object, plus:
typeCasting: boolean - auto-convert values to the variable's defined type (default: true)

Returns: Array<BucketedFeature>

Full Example

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

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const features: BucketedFeature[] = context.runFeatures();
  console.log(features);
});

Run a Single Feature

Returns a single feature's status and variable values for the visitor.

const feature: BucketedFeature = userContext.runFeature('feature-key');

// With attributes and experience filter:
const feature: BucketedFeature = userContext.runFeature('feature-key', {
  locationProperties: { url: '/settings' },
  visitorProperties: { role: 'admin' },
  typeCasting: true,
  experienceKeys: ['specific-experience-key']
});

Parameters:

Parameter Type Required Description
featureKey string Yes The feature's unique key
attributes object No See Attributes Object, plus:
typeCasting: boolean - auto-convert values to the variable's defined type (default: true)
experienceKeys: string[] - limit evaluation to specific experiences only

Returns: BucketedFeature (see Data Model > BucketedFeature)

Full Example

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

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx'
} as ConvertConfig);

convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const feature: BucketedFeature = context.runFeature('feature-key');

  if (feature && feature.status === 'enabled') {
    console.log('Feature is enabled with variables:', feature.variables);
  }
});

Tracking Conversions

Sends a conversion event for a goal. The decision is made against the goal's configured triggering rules.

userContext.trackConversion('goal-key', {
  ruleData: {
    action: 'buy'
  },
  conversionData: [
    { key: 'amount', value: 10.3 },
    { key: 'productsCount', value: 2 },
    { key: 'transactionId', value: 'transaction-unique-id' }
  ],
  conversionSetting: {
    forceMultipleTransactions: false
  }
});

Parameters:

Parameter Type Required Description
goalKey string Yes The goal's unique key
attributes object No Conversion attributes (see below)

Attributes:

Property Type Description
ruleData object Key-value pairs used for goal rule matching
conversionData Array<object> Transaction data entries. Each entry accepts:
amount (number) - order value
productsCount (number) - order quantity
transactionId (string | number) - unique transaction identifier
conversionSetting object Tracking settings:
forceMultipleTransactions (boolean) - whether to accumulate revenue for the same visitor

Returns: void

Full Example

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

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.trackConversion('goal-key', {
    ruleData: {
      action: 'buy'
    },
    conversionData: [
      {
        key: 'amount',
        value: 10.3
      },
      {
        key: 'productsCount',
        value: 2
      },
      {
        key: 'transactionId',
        value: 'transaction-unique-id'
      }
    ],
    conversionSetting: {
      forceMultipleTransactions: false
    }
  });
});

Segments

Run Custom Segments

Evaluates segment rules and updates custom segments in the user context.

userContext.runCustomSegments(['segment-key-1', 'segment-key-2'], {
  enabled: true
});

Parameters:

Parameter Type Required Description
segmentsKeys string[] Yes List of segment keys to evaluate
visitorProperties object No Key-value pairs used for segment matching

Returns: void

Full Example

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

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.runCustomSegments(['segment-key'], {
    enabled: true
  });
});

Set Default Segments

Permanently updates the visitor's default segments for reporting. Only the following properties are included in Convert Reports:

  • browser
  • devices
  • source
  • campaign
  • visitorType
  • country
userContext.setDefaultSegments({
  country: 'US',
  browser: 'chrome',
  devices: 'desktop'
});

Parameters:

Parameter Type Required Description
segments object Yes Key-value pairs merged with the initial visitor properties

Returns: void

Visitor Properties

Update Visitor Properties

Permanently updates all visitor properties used in audience evaluation.

userContext.updateVisitorProperties({
  weather: 'rainy',
  plan: 'enterprise'
});

Parameters:

Parameter Type Required Description
visitorProperties object Yes Key-value pairs merged with the initial visitor properties

Returns: void

Visitor properties can also be updated inline when calling any experience/feature method by setting updateVisitorProperties: true in the attributes object:

const variation = userContext.runExperience('experience-key', {
  visitorProperties: { weather: 'rainy' },
  updateVisitorProperties: true
});

Config Entity Lookup

Get Config Entity by Key

Find a single entity in the project configuration by its key.

import ConvertSDK, {EntityType} from '@convertcom/js-sdk';
import type {Experience} from '@convertcom/js-sdk';

const experience: Experience = userContext.getConfigEntity(
  'experience-key',
  EntityType.EXPERIENCE
);

Parameters:

Parameter Type Required Description
key string Yes Entity key
entityType EntityType Yes One of: EntityType.AUDIENCE, EntityType.LOCATION, EntityType.SEGMENT, EntityType.FEATURE, EntityType.GOAL, EntityType.EXPERIENCE, EntityType.VARIATION

Returns: The matching entity object or null.

Get Config Entity by ID

Find a single entity in the project configuration by its numeric id.

import ConvertSDK, {EntityType, VariationChangeType} from '@convertcom/js-sdk';
import type {BucketedVariation, Feature, VariationChange} from '@convertcom/js-sdk';

const variation: BucketedVariation = userContext.runExperience('experience-key');
const changesData: VariationChange = variation.changes.find(
  ({type}) => type === VariationChangeType.FULLSTACK_FEATURE
);
const feature: Feature = userContext.getConfigEntityById(
  changesData.data.feature_id,
  EntityType.FEATURE
);

Parameters:

Parameter Type Required Description
id number Yes Entity numeric ID
entityType EntityType Yes Same values as getConfigEntity above

Returns: The matching entity object or null.

Releasing Queues

The SDK batches tracking events and sends them periodically (configured via events.batch_size and events.release_interval). You can manually flush all pending queues.

const variations: BucketedVariation[] = userContext.runExperiences();

// Manually release all pending queues (e.g. on component unmount, button click, navigation)
userContext.releaseQueues().then(() => {
  console.log('all pending queues have been released');
});

// With a reason (for debugging)
userContext.releaseQueues('page-exit');

Parameters:

Parameter Type Required Description
reason string No Custom message for debugging

Returns: Promise<void>

This is especially important in short-lived environments like Cloudflare Workers where the event batch timer may not have time to fire. See Cloudflare Workers for edge-specific patterns.

Events

The SDK emits events that you can subscribe to for logging, analytics integrations, or debugging.

Available Events

Event Triggered By Callback Data
ready SDK initialization complete null
bucketing Running experience(s) { visitorId: string, experienceKey: string, variationKey: string }
Running feature(s) { visitorId: string, experienceKey: string, featureKey: string, status: string }
conversion Tracking a conversion { visitorId: string, goalKey: string }
location.activated Location rules matched { visitorId: string, location: { id: string, name: string, key: string } }
location.deactivated Location rules no longer matched (only if activated earlier) { visitorId: string, location: { id: string, name: string, key: string } }
config.updated Configuration refreshed from CDN null

Subscribing to Events

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

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx'
} as ConvertConfig);

// Ready event
convertSDK.on(SystemEvents.READY, function (res, err) {
  if (err) {
    console.error(err);
  }
});

// Bucketing event (e.g. for GA integration)
convertSDK.on(
  SystemEvents.BUCKETING,
  function ({visitorId, experienceKey, variationKey, featureKey, status}, err) {
    if (err) {
      console.error(err);
    } else {
      console.log(visitorId, experienceKey, variationKey, featureKey, status);

      // Example: Google Analytics integration
      const experienceName = context.getConfigEntity(
        experienceKey, EntityType.EXPERIENCE
      ).name;
      const variationName = context.getConfigEntity(
        variationKey, EntityType.VARIATION
      ).name;
      gtag('event', 'convert_bucketing', {
        experienceName,
        variationName
      });
    }
  }
);

// Conversion event
convertSDK.on(SystemEvents.CONVERSION, function ({visitorId, goalKey}, err) {
  if (err) {
    console.error(err);
  } else {
    console.log(visitorId, goalKey);
  }
});

// Config updated event
convertSDK.on(SystemEvents.CONFIG_UPDATED, function (res, err) {
  if (err) {
    console.error(err);
  }
});

See EventManager for how the pub/sub system works internally, including deferred events.

Persistent DataStore

You can provide your own DataStore to make bucketing persistent across sessions. The DataStore interface requires two methods: set and get.

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

class CustomDataStore {
  #data = {};

  get(key) {
    if (!key) return this.#data;
    return this.#data[key.toString()];
  }

  set(key, value) {
    if (!key) throw new Error('Invalid CustomDataStore key!');
    this.#data[key.toString()] = value;
  }
}

const dataStore = new CustomDataStore();
const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx',
  dataStore
} as ConvertConfig);

Without a DataStore, bucketing decisions are only kept in-memory for the current session. With a DataStore, the SDK reads from and writes to it via a DataStoreManager wrapper (see DataManager for details).

For Cloudflare Workers environments, use the KVDataStore from @convertcom/js-sdk-cloudflare. See Cloudflare Workers for details.

Copyrights © 2025 All Rights Reserved by Convert Insights, Inc.

Getting Started

JavaScript SDK

Core Concepts

How-To Guides

Edge & Integrations

Contributing

Clone this wiki locally