Configuration Options

Full SDK config reference

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

FieldTypeRequiredDefaultDescription
sdkKeystringYes (or data)Project identifier. The SDK fetches configuration from Convert's CDN using this key.
sdkKeySecretstringNoRequired when using an authenticated SDK key.
environmentstringNoEnvironment to match rules against ('staging' or 'production').
dataobjectYes (or sdkKey)Static project configuration object (alternative to sdkKey).
dataStoreobject | nullNonullPersistent DataStore for bucketing decisions across sessions. Must implement get(key) and set(key, value).
dataRefreshIntervalnumberNo300000How often (in ms) to refresh configuration from the CDN.
debugTokenstringNoQA/debug secret that widens the config fetch to every non-archived experience, drafts and paused ones included. See Debug Token below.

logger

FieldTypeDefaultDescription
logLevelLogLevelLogLevel.DEBUGMinimum log level: DEBUG, INFO, WARN, ERROR, SILENT.
customLoggersarray[]Array of third-party logger instances.

bucketing

FieldTypeDefaultDescription
hash_seednumber9999Seed value for the MurmurHash algorithm.
max_trafficnumber10000Maximum hash value representing 100% traffic allocation.
excludeExperienceIdHashbooleanfalseWhether to ignore prefixing the generated hash with the experience ID.

events

FieldTypeDefaultDescription
batch_sizenumber10Maximum number of network requests released per batch.
release_intervalnumber1000Time in milliseconds between queue releases.

network

FieldTypeDefaultDescription
trackingbooleantrueSet to false to disable sending tracking events to Convert.
cacheLevelstring'default'Set to 'low' for short-lived cache (development only).
sourcestring'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


Did this page help you?