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.

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
}

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

ConvertConfiguration parameters

Notes on key options

logLevel

networkTracking

dataRefreshIntervalMs

bucketingHashSeed and bucketingMaxTraffic

apiConfigEndpoint / apiTrackEndpoint

networkCacheLevel