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
| Key | Type | Default | Meaning |
|---|---|---|---|
key | String (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. |
endpoint | String (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. |
screenTracking | ScreenTracking (.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. |
debug | Bool | false | Enables 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.beforeDecision | BeforeDecision (.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.source | ConsentSource (.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) | .webView | Governs 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):
beforeDecisionis silently overridden to.sendno matter what you wrote — seeOptimaConfig.init: "source=.cmp hands the decision to the CMP: buffering would wait for a decision that is not ours to make."- The SDK stops declaring its own consent state (
consent.set,consent.get().decisions) as thepurposesarray on outgoing requests. It still merges in whatever you feedconsent.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 field | Maps to |
|---|---|
$context.url | url (the app://<bundle-id>/<screen> convention — see chapter 5) |
$context.title | screen name |
$props.session_id | session id |
$props.session_start | session-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.