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
| 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
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
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
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
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
- Initialization -- how to use these config options when starting the SDK
- Code Examples -- complete examples for every SDK method
- QA & Preview -- debug tokens and preview links
Updated 21 days ago