Configuration

Configuration Options

This page is the reference for every field of every config dataclass the SDK accepts: SDKConfig, TransportConfig, and RefreshConfig.

For the broader narrative on initialization modes (SDK key vs. direct config, opt-in refresh), see Initialization.

SDKConfig

Top-level config passed to Core(SDKConfig(...)). Exactly one of sdk_key or data must be provided.

from convert_sdk import Core, SDKConfig, TransportConfig, RefreshConfig

core = Core(
    SDKConfig(
        sdk_key="your-sdk-key",   # or: data={...} for offline/direct mode
        environment="production",
        transport=TransportConfig(),
        batch_size=10,
        auto_flush_interval_ms=None,
        refresh=None,
    )
).initialize()

Field	Type	Default	Purpose
sdk_key	str | None	None	Convert project SDK key. Used when fetching config remotely. Mutually exclusive with data.
data	dict | None	None	Inline project-config payload. Mutually exclusive with sdk_key. No network call is made.
environment	str | None	None	Optional environment filter. When set, the config route appends environment={environment} (JS parity).
cache_level	str | None	None	Optional cache level. "low" appends _conv_low_cache=1 to the config route (JS parity).
transport	TransportConfig	TransportConfig()	Network settings for the config-fetch and tracking delivery.
batch_size	int	10	Number of queued tracking events that triggers a batch-size queue release. Must be a positive integer.
auto_flush_interval_ms	int | None	None	Opt-in periodic-flush interval in milliseconds. None keeps the lifecycle explicit-flush-only. When set, a daemonic timer periodically releases the queue.
data_store	DataStore | None	None	Optional shared persistence adapter. None selects the per-process InMemoryDataStore.
logger	logging.Logger | None	None	Optional caller-supplied logger. None uses the "convert_sdk" namespace logger. The SDK never adds handlers or sets levels.
refresh	RefreshConfig | None	None	Opt-in background config refresh. None means refresh is off.

Validation (raised as InvalidConfigError from SDKConfig.__init__):

• Exactly one of sdk_key or data must be provided.
• sdk_key, when supplied, must be a non-empty string.
• data, when supplied, must be a mapping/dict.
• cache_level must be None or "low".
• batch_size must be a positive integer.
• auto_flush_interval_ms, when supplied, must be a positive integer.

Note: there is no separate TrackingConfig class. Queue and batching settings (batch_size, auto_flush_interval_ms) are fields directly on SDKConfig.

TransportConfig

Network settings for the bundled httpx-backed transport.

from convert_sdk import TransportConfig

transport = TransportConfig(
    base_url="https://cdn-4.convertexperiments.com",
    timeout=10.0,
    auth_secret=None,
    headers={},
    verify_tls=True,
)

Field	Type	Default	Purpose
base_url	str	"https://cdn-4.convertexperiments.com"	HTTPS base URL of the config-serving endpoint. Must use the https scheme — a non-HTTPS URL raises TransportError (NFR8).
timeout	float	10.0	Per-request timeout in seconds.
auth_secret	str | None	None	Optional bearer secret injected as an Authorization header on config and tracking requests.
headers	Mapping[str, str]	{}	Optional extra headers appended to every config request.
verify_tls	bool	True	Whether to verify TLS certificates.

A non-HTTPS base_url raises TransportError at construction time, before any network I/O.

RefreshConfig

Background config-refresh policy. Opt-in; SDKConfig.refresh=None keeps refresh off (the default). Only applies when sdk_key mode is used — supplying a RefreshConfig in direct-config (data) mode logs a refresh.skipped diagnostic and starts no worker.

from convert_sdk import RefreshConfig

refresh = RefreshConfig(
    interval_seconds=300.0,
    jitter_seconds=30.0,
    backoff_factor=2.0,
    backoff_max_seconds=600.0,
)

Field	Type	Default	Purpose
interval_seconds	float	300.0	Base period between successful refreshes. Must be > 0.
jitter_seconds	float	30.0	Max uniform random jitter added per cycle. Must satisfy 0 <= jitter <= interval.
backoff_factor	float	2.0	Exponential multiplier applied per consecutive failure. Must be >= 1.0.
backoff_max_seconds	float	600.0	Ceiling on the backed-off wait. Must be >= interval_seconds.

Validation errors raise InvalidConfigError at RefreshConfig construction.

Recommended configurations

Long-running web service (Django/Flask/FastAPI)

import os
from convert_sdk import SDKConfig, RefreshConfig

config = SDKConfig(
    sdk_key=os.environ["CONVERT_SDK_KEY"],
    environment="production",
    batch_size=25,
    refresh=RefreshConfig(
        interval_seconds=300.0,
        jitter_seconds=30.0,
        backoff_factor=2.0,
        backoff_max_seconds=600.0,
    ),
)

Auto-refresh keeps long-lived processes from drifting on stale config; a larger batch_size amortises the per-request flush cost.

Short-lived script / cron job

import os
from convert_sdk import SDKConfig

config = SDKConfig(
    sdk_key=os.environ["CONVERT_SDK_KEY"],
    environment="production",
    # refresh=None — process exits before a single interval would tick
)

Tests / CI

from convert_sdk import SDKConfig

config = SDKConfig(
    data={...},  # inline payload — no network call
)

See Testing for the full pattern.

What to read next

• Initialization — narrative on init modes and refresh
• Code Examples — practical use of each option
• Type Hints — dataclass field types and helper enums
• Extending — custom transport, storage, and event-bus