Configuration

Configuration Options

Every option is set as a parameter on ConvertConfiguration and is optional except sdkKey (or use the ConvertSwiftSDK(configData:) initializer to bypass the key entirely). Set what you need and leave the rest at their defaults. All options mirror the Convert JS SDK's Config type — if you are porting from the JS SDK, each field is reachable through the ConvertConfiguration initializer.

import ConvertSwiftSDK

let config = ConvertConfiguration(
    sdkKey: "YOUR_SDK_KEY",
    environment: "prod",
    logLevel: .info
)
let sdk = ConvertSwiftSDK(configuration: config)

There is no builder chain on iOS — ConvertConfiguration is an immutable value type constructed once and passed to the ConvertSwiftSDK initializer. The two public initializers are:

// Key path: fetches config from the CDN on first ready().
let sdk = ConvertSwiftSDK(configuration: ConvertConfiguration(sdkKey: "YOUR_SDK_KEY"))

// Direct-data path: bypasses the CDN; validates the payload on ready().
let sdk = ConvertSwiftSDK(configData: preloadedData)

ConvertConfiguration parameters

All parameters except sdkKey carry defaults. The table lists every public parameter, its type, and its default value (verified against Sources/ConvertSwiftSDKCore/Config/ConvertConfiguration.swift and Defaults.swift):

Parameter	Type	Default	Purpose
sdkKey	String	required	The project SDK key identifying the Convert project to load.
sdkKeySecret	String?	nil	Optional SDK key secret for authenticated endpoints.
environment	String?	nil	Optional environment selector (e.g. "staging" / "prod").
apiConfigEndpoint	String	"https://cdn-4.convertexperiments.com/api/v1"	Base URL for fetching project configuration. No trailing slash.
apiTrackEndpoint	String	"https://cdn-4.convertexperiments.com/api/v1"	Base URL for delivering tracking events. No trailing slash.
bucketingMaxTraffic	Int	10_000	Inclusive upper bound of the bucketing traffic range (basis points).
bucketingHashSeed	UInt32	9_999	MurmurHash3 seed used when hashing the bucketing key.
dataRefreshIntervalMs	Int	300_000 (5 min)	Interval in milliseconds between remote configuration refreshes.
eventsBatchSize	Int	10	Number of queued events flushed per release batch.
eventsReleaseIntervalMs	Int	1_000 (1 s)	Interval in milliseconds between event-queue release attempts.
ruleKeysCaseSensitive	Bool	true	Whether rule key comparisons are case-sensitive.
ruleNegation	Bool	false	Whether rule matching applies negation semantics.
logLevel	LogLevel	.warn	Minimum log severity; messages below this level are suppressed.
networkTracking	Bool	true	Boot-time tracking switch — the static network.tracking gate.
networkCacheLevel	CacheLevel	.normal	CDN cache directive applied to config fetches.
debugToken	String?	nil	QA debug token. While set, config fetches carry it, force the low-cache bypass, and never touch the on-disk config cache.

Notes on key options

logLevel

Accepts any LogLevel case. Use .debug while integrating; the default .warn keeps production logs quiet. See Logging during development below and Return Types & Models for the full LogLevel enum.

networkTracking

The boot-time equivalent of calling sdk.setTrackingEnabled(false) before any event fires. Set to false when consent is unknown at launch; use sdk.setTrackingEnabled(_:) async at runtime once consent resolves. See Tracking Control.

dataRefreshIntervalMs

Drives the foreground config-refresh scheduler. The scheduler runs only after the first config has loaded and only while the app is in the foreground. The iOS default of 300_000 ms (5 minutes) differs from the Android default of 600_000 ms (10 minutes) — read the constant from Defaults.dataRefreshIntervalMs rather than hard-coding it.

bucketingHashSeed and bucketingMaxTraffic

These drive MurmurHash3 bucketing math. Leave them at their JS-parity defaults unless you are matching a legacy account's bucketing. Changing either breaks cross-SDK bucketing agreement. See the Bucketing Algorithm doc.

apiConfigEndpoint / apiTrackEndpoint

Both default to the Convert CDN base (https://cdn-4.convertexperiments.com/api/v1). Override for staging or on-premises deployments. Route paths carry the leading /, so the base must not have a trailing slash.

networkCacheLevel

Controls the CDN cache TTL applied to config fetches:

public enum CacheLevel: String, Sendable, CaseIterable {
    case normal  // standard CDN caching
    case low     // appends `_conv_low_cache=1` to request a lower TTL
}

debugToken

A QA debug token widens the config the SDK receives to every non-archived experience — drafts and paused ones included — so you can build against experiments that are not serving yet. Generate one from a variation's Preview panel in the Convert app; a token is valid for 24 hours, then expires.

let sdk = ConvertSwiftSDK(configuration: ConvertConfiguration(
    sdkKey: "YOUR_SDK_KEY",
    debugToken: "YOUR_DEBUG_TOKEN"
))

While a token is set:

• Config fetches carry it as a debug_token query parameter. It rides config requests only — never the tracking endpoint.
• The low-cache bypass is forced regardless of networkCacheLevel, so QA changes appear immediately.
• The on-disk config cache is skipped in both directions: a debug config is never read from it, and never written to it, so a QA session cannot poison the cache a normal launch loads.
• The token is stripped from SDK log output in full — the parameter name as well as the value — so it cannot be fingerprinted in aggregated logs.

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

Preview links are the other half of this workflow and need no debug token — see QA & Preview for both, and Code Examples for the setPreview wiring.

Logging during development

import ConvertSwiftSDK

let sdk = ConvertSwiftSDK(configuration: ConvertConfiguration(
    sdkKey: "YOUR_SDK_KEY",
    logLevel: .debug
))

The SDK logs through the Logger port using the tag ConvertSwiftSDK. When you inject the platform OSLog adapter (or when a real logging adapter is supplied), logs appear in the Xcode console or Console.app at the matching severity. There is no adb logcat equivalent on iOS — use the Xcode Debug console or os_log tooling.

Runtime tracking toggle

networkTracking on ConvertConfiguration is a one-time, immutable boot-time flag. To toggle tracking at runtime (e.g. on consent withdrawal), use the async API on the SDK handle:

// suppress tracking immediately
await sdk.setTrackingEnabled(false)

// re-enable after consent is obtained
await sdk.setTrackingEnabled(true)

// read the current runtime state
let isOn = await sdk.isTrackingEnabled()

Or the completion-handler bridge (delivered on MainActor):

sdk.setTrackingEnabled(false) { /* called on MainActor when the gate is closed */ }
sdk.isTrackingEnabled { isOn in print("tracking:", isOn) }

See Tracking Control for the full consent matrix and three-layer model.

Next steps

• Initialization — ConvertSwiftSDK.init, ready(), and the direct-data path
• Return Types & Models — LogLevel, CacheLevel, and the other enums
• Tracking Control — the tracking switch in depth