Skip to content
Optima docs
SDKsiOS SDK

Configuration

iOS SDK v1.4.0 — Configuration

OptimaConfig is built once, at Optima.initialize time, and is immutable afterward — there is no way to change endpoint or screenTracking mid-run short of a process restart. It uses a small nested-builder closure, mirroring the Android SDK's DSL as closely as Swift's syntax allows:

let config = try OptimaConfig(key: "oek_shop_a1b2c3", endpoint: "https://edge.shop.example") {
    $0.screenTracking = .manual        // .manual (default) | .auto
    $0.debug = false
    $0.consent.beforeDecision = .buffer // .buffer (default) | .send
    $0.consent.source = .optima         // .optima (default) | .cmp
    $0.display.htmlMode = .webView      // .webView (default) | .off
    $0.display.htmlUrlSchemes = ["tel"] // extra schemes HTML links may open
}
Optima.initialize(config)

Keys

KeyTypeDefaultMeaning
keyString (initializer, required)—The Edge SDK key (oek_...). Validated non-blank at build time (OptimaConfig.key is required, throws SdkError); sent as the X-Edge-Key header on every request. See The SDK key below for where it comes from.
endpointString (initializer, required)—The base URL of your Optima Edge gateway, e.g. https://edge.shop.example. Must start with http (validated at build time: OptimaConfig.endpoint must be an absolute http(s) URL); a trailing slash is stripped for you. Every SDK request is <endpoint>/edge/v1/... — nothing else is ever called.
screenTrackingScreenTracking (.manual | .auto).manual.manual: you call screen(name) (or the SwiftUI .optimaScreen(name) modifier) yourself wherever a screen change happens. .auto: the SDK swizzles UIViewController.viewDidAppear(_:) once and reports the presenting controller's type name, skipping UIKit containers, UIHostingController, SFSafariViewController and UIAlertController (their names carry no screen meaning). Either way, the launching URL is captured for attribution via your own captureURL(_:) call (chapter 1) — that isn't gated by this setting at all.
debugBoolfalseEnables verbose os_log (Darwin) / stderr (elsewhere) output under the optima/com.optima.sdk tag: every enqueue, flush, server response, dropped item and internal error. Leave this off in release builds — it's a local log-verbosity switch, not a data-plane one.
consent.beforeDecisionBeforeDecision (.buffer | .send).buffer.buffer: hits queue in the on-disk outbox but are not flushed to the server until a consent decision exists (consent.get().decided == true) — the first consent.set(...) call unblocks the queue. .send: hits flush immediately regardless of whether consent has been decided yet. Forced to .send automatically whenever consent.source = .cmp — a CMP-driven app doesn't own the decision, so there's nothing of ours to buffer for; see the source row below.
consent.sourceConsentSource (.optima | .cmp).optima.optima: the SDK declares its own purposes array on every request, built from consent.get().decisions (see chapter 4 for the omit-vs-[] rule). .cmp: the SDK never declares its own purposes — a served banner_consent content item is not rendered by the built-in ConsentBannerView but instead surfaces as a plain .contentItem event for you to route to your CMP SDK, and you drive consent entirely through consent.setKeys/setGCM/setTCF (TCF is still read automatically, see chapter 4).
display.htmlMode (htmlMode inside the display block)HtmlMode (.webView | .off).webViewGoverns only unstructured content items (raw operator-authored HTML/CSS/JS). .webView: OptimaSDKUI's renderers show them in an isolated WKWebView (a non-persistent WKWebsiteDataStore — no cookies or storage shared with the rest of the app, see chapter 5). .off: unstructured items are never rendered; they still surface as .contentItem/.contentLoaded events if you want to do something else with them.
display.htmlUrlSchemes (htmlUrlSchemes)Set<String>[]Extra URL schemes a link inside an HTML item may open. http/https and the schemes your app registers in Info.plist (CFBundleURLTypes) are always allowed; everything else (tel:, sms:, mailto:, other apps' schemes) is refused unless listed here (case-insensitive). Structured items' cta_url is not affected. See chapter 5.

The source = .cmp rule, once more explicitly

Setting consent.source = .cmp is a one-way toggle on two independent behaviours, fixed for the life of the config object (OptimaConfig.init applies the override before storing anything, so it's baked in — there is no way to read the un-overridden beforeDecision back out):

  1. beforeDecision is silently overridden to .send no matter what you wrote — see OptimaConfig.init: "source=.cmp hands the decision to the CMP: buffering would wait for a decision that is not ours to make."
  2. The SDK stops declaring its own consent state (consent.set, consent.get().decisions) as the purposes array on outgoing requests. It still merges in whatever you feed consent.setKeys/setGCM/setTCF.

Use source = .cmp only when a separate, already-integrated CMP SDK (OneTrust, Didomi, a TCF-compliant vendor, …) is the actual system of record for consent in your app. Otherwise leave source = .optima and let the built-in banner (see chapter 4) do the work.

The SDK key

Keys are created in the Optima console under Edge → SDK keys. The key's platform determines which surfaces it can reach and how the edge worker resolves the device to a profile — create (or ask your Optima operator to create) a key on the mobile platform specifically for this app, not a web key repurposed for mobile traffic. A web-platform key presented from this SDK will generally still authenticate (the X-Edge-Key check doesn't distinguish platforms at that layer), but content targeting, the tracking entity resolution (edge_settings.mobile_entity_type / mobile_device_identifier_key), and origin/App-ID allowlisting are all platform-scoped server-side, so a mismatched platform key produces confusing gaps rather than a clean error. See chapter 9 for what a wrong-platform or revoked key looks like from the SDK's side.

The screen_view category mapping

Every screen() call becomes a track("screen_view", name: ...) hit under the hood (OptimaRuntime.screen, chapter 3). Like every other tracking category, screen_view lands only if an operator has mapped it in the Optima console — an unmapped category is dropped server-side as unknown_category (counted in the track response's dropped array and surfaced as a .track event, never a hard error). This is the same rule the Web and Android SDKs' screen_view/page_view categories follow.

The recommended category mapping for screen_view (create this once, in the Optima console's category-mapping screen, before shipping):

Source fieldMaps to
$context.urlurl (the app://<bundle-id>/<screen> convention — see chapter 5)
$context.titlescreen name
$props.session_idsession id
$props.session_startsession-start marker
the UTM/click-id props (utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid)attribution props

Add your app's own event categories (add_to_cart, purchase, ...) the same way — nothing about screen_view is special beyond being the one category every install needs mapped for .auto tracking (or your manual screen() calls) to be visible in analytics at all.

On this page