Skip to content

Configuration

Ahmed Abbas edited this page Jul 31, 2026 · 3 revisions

JavaScript SDK — Configuration

The full SDK configuration options object with all available fields.

Configuration Options

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

const config = {
  sdkKey: '',              // either this or 'data' is required
  sdkKeySecret: '',        // required when using an authenticated SDK key
  environment: 'staging',
  logger: {
    logLevel: LogLevel.DEBUG,
    customLoggers: []      // allows 3rd party loggers
  },
  bucketing: {
    hash_seed: 9999,              // MurmurHash seed
    max_traffic: 10000,           // max hash value (100% traffic)
    excludeExperienceIdHash: false // whether to ignore prefixing hash with experience id
  },
  dataStore: null,         // optional persistent DataStore (see Persistent DataStore below)
  dataRefreshInterval: 300000, // config refresh interval in ms (5 minutes)
  data: projectData,       // static project configuration (alternative to sdkKey)
  events: {
    batch_size: 10,        // max events per network batch
    release_interval: 1000 // time in ms between queue releases
  },
  network: {
    tracking: true,        // set false to disable tracking events
    cacheLevel: 'default', // 'low' for short-lived cache (dev only)
    source: 'js-sdk'       // source identifier in network requests
  },
  debugToken: ''           // QA only -- never ship to production
};

Field Reference

Top-Level Fields

Field Type Required Default Description
sdkKey string Yes (or data) Project identifier. The SDK fetches configuration from Convert's CDN using this key.
sdkKeySecret string No Required when using an authenticated SDK key.
environment string No Environment to match rules against ('staging' or 'production').
data object Yes (or sdkKey) Static project configuration object (alternative to sdkKey).
dataStore object | null No null Persistent DataStore for bucketing decisions across sessions. Must implement get(key) and set(key, value).
dataRefreshInterval number No 300000 How often (in ms) to refresh configuration from the CDN.
debugToken string No QA/debug secret that widens the config fetch to every non-archived experience, drafts and paused ones included. See Debug Token below.

logger

Field Type Default Description
logLevel LogLevel LogLevel.DEBUG Minimum log level: DEBUG, INFO, WARN, ERROR, SILENT.
customLoggers array [] Array of third-party logger instances.

bucketing

Field Type Default Description
hash_seed number 9999 Seed value for the MurmurHash algorithm.
max_traffic number 10000 Maximum hash value representing 100% traffic allocation.
excludeExperienceIdHash boolean false Whether to ignore prefixing the generated hash with the experience ID.

events

Field Type Default Description
batch_size number 10 Maximum number of network requests released per batch.
release_interval number 1000 Time in milliseconds between queue releases.

network

Field Type Default Description
tracking boolean true Set to false to disable sending tracking events to Convert.
cacheLevel string 'default' Set to 'low' for short-lived cache (development only).
source string 'js-sdk' Source identifier included in network requests.

Debug Token

By default the SDK receives only the experiences that are actively serving. Setting debugToken widens the config fetch to every non-archived experience — drafts and paused ones included — and bypasses the server-side config cache, so QA changes appear immediately.

const convertSDK = new ConvertSDK({
  sdkKey: 'xxx',
  debugToken: 'your-debug-token'
} as ConvertConfig);

Generate a token from a variation's Preview panel in the Convert app; it expires after 24 hours. While it is set, the SDK also lowers its own config cache level regardless of network.cacheLevel.

The token is sent only on config requests — never to the tracking endpoint. Treat it as a secret and keep it out of your logs.

Never ship a debug token to production. It exposes unreleased experiments in the config. Keep it behind an environment variable in a QA/staging build and remove it before release.

Previewing a single variation needs no debug token at all — see QA & Preview.

Project Data Structure

The data / projectData structure is documented in the Data Model and at the Convert Serving API docs.

Next Steps

Clone this wiki locally