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):

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