Configuration

Configuration Options

This page is the reference for every field of every config dataclass the SDK accepts: SDKConfig, TransportConfig, TrackingConfig, 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(...)).

from convert_sdk import Core, SDKConfig, TransportConfig, TrackingConfig
from convert_sdk.config import RefreshConfig

core = Core(
    SDKConfig(
        sdk_key="your-sdk-key",
        sdk_key_secret=None,
        config_data=None,
        environment="production",
        transport=TransportConfig(),
        tracking=TrackingConfig(),
        refresh=None,
    )
)

Field	Type	Default	Purpose
sdk_key	str | None	None	Convert project SDK key. Used when fetching config and tracking.
sdk_key_secret	str | None	None	Optional HMAC secret. Sent as Authorization: Bearer … on config and tracking requests.
config_data	Mapping[str, Any] | None	None	Inline project-config payload. Mutually exclusive with sdk_key-mode network fetch.
environment	str | None	None	Environment filter applied to experience eligibility. Match it to the dashboard's environments value.
transport	TransportConfig	TransportConfig()	Network settings for both config and tracking.
tracking	TrackingConfig	TrackingConfig()	Queue settings for conversion delivery.
refresh	RefreshConfig | None	None	Opt-in background config refresh. None means refresh is off.

Validation (raised as ConfigValidationError from Core.__init__):

• Exactly one of sdk_key or config_data must be provided.
• environment, when supplied, must be a non-empty string.
• refresh, when supplied, must satisfy its own __post_init__ validation.

TransportConfig

Network settings for the bundled HttpxTransport. Passing a custom Transport implementation makes most of these fields advisory — your adapter chooses what to honour.

from convert_sdk import TransportConfig

transport = TransportConfig(
    config_endpoint="https://cdn-4.convertexperiments.com/api/v1",
    tracking_endpoint="https://metrics.convertexperiments.com/v1",
    headers={},
    timeout_seconds=5.0,
    verify_tls=True,
)

Field	Type	Default	Purpose
config_endpoint	str	"https://cdn-4.convertexperiments.com/api/v1"	Base URL for the config-fetch GET.
tracking_endpoint	str	"https://metrics.convertexperiments.com/v1"	Base URL for tracking POSTs.
headers	Mapping[str, str]	{}	Extra HTTP headers appended to every config + tracking request.
timeout_seconds	float	5.0	Per-request timeout passed to httpx.Client.
verify_tls	bool	True	Whether the bundled transport verifies TLS certificates.

TrackingConfig

Conversion-queue settings.

from convert_sdk import TrackingConfig

tracking = TrackingConfig(
    batch_size=10,
    source="python-sdk",
    enrich_data=True,
)

Field	Type	Default	Purpose
batch_size	int	10	Maximum events per outgoing tracking POST. Larger values reduce network calls; smaller values reduce per-flush latency.
source	str	"python-sdk"	Value placed in the source field of the tracking payload. Useful for telemetry segmentation.
enrich_data	bool	True	Whether to set enrichData: true on the tracking payload. Disable only when you intend to handle enrichment server-side.

RefreshConfig

Background config-refresh policy. Opt-in; SDKConfig.refresh=None keeps refresh off.

from convert_sdk.config import RefreshConfig

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

Field	Type	Default	Purpose
interval_seconds	float	(required)	Base refresh interval. Must be > 0.
jitter_seconds	float	0.0	Per-tick uniform jitter, applied as ±jitter. Must satisfy 0 ≤ jitter ≤ interval.
backoff_initial_seconds	float	(required)	First retry wait after a transient failure. Must be > 0.
backoff_factor	float	(required)	Multiplier applied per consecutive failure. Must be > 1.0 (strict).
backoff_max_seconds	float	(required)	Cap for the backoff sleep. Must be > backoff_initial_seconds (strict).
on_terminal_failure	Callable[[Exception], None] | None	None	Optional callback invoked at most once per terminal failure. Exceptions inside the callback are caught and logged.

Validation errors carry one of three codes: refresh.invalid_interval, refresh.invalid_jitter, or refresh.invalid_backoff.

Constructor keyword arguments

Core accepts a few additional kwargs for swapping built-in adapters with custom implementations. These are documented in Extending.

Kwarg	Type	When to use
transport	Transport	Replace the HTTP layer (mTLS, proxy, async wrapper, stub).
data_store	DataStore	Replace visitor-state persistence (Redis, Postgres).
event_bus	EventBus	Replace the in-memory pub/sub for lifecycle events.

from convert_sdk import Core, SDKConfig, InMemoryDataStore

core = Core(
    SDKConfig(config_data=project_config),
    transport=my_custom_transport,
    data_store=InMemoryDataStore(),
)

Recommended configurations

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

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

Auto-refresh keeps long-lived processes from drifting on stale config; a larger batch_size amortises the per-request flush cost when each request flushes its own queue.

Short-lived script / cron job

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

Tests / CI

SDKConfig(
    config_data={...},  # inline payload
    # transport= a stub if you also exercise tracking
)

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