Differences from the Android and Web SDKs
iOS SDK v1.4.0 — Differences from the Android and Web SDKs
The iOS SDK follows the Android SDK
and the Web SDK as closely as the
platform allows — same event names, same wire contract
(contract/oapi3_edge.yml), same consent semantics. Where it diverges, it's
a deliberate consequence of iOS's platform APIs, or of an iteration boundary
for this first release. These tables are the authoritative list; most rows
are discussed in more depth in the chapter their right-hand column links to.
Differences from the Android SDK
| Android | iOS | Why |
|---|---|---|
screenTracking = AUTO by default via ActivityLifecycleCallbacks | default .manual; .optimaScreen("Name") SwiftUI modifier; .auto swizzles UIViewController.viewDidAppear (opt-in) | iOS has no public lifecycle hook that names screens; swizzling is the one mechanism that cannot be verified on Linux, so it is not the default (chapter 2) |
captureReferrer(String) (Play Install Referrer) | captureURL(URL) | iOS has no install-referrer API; attribution comes only from the launching universal link / custom scheme, which the app hands over from its onOpenURL/SceneDelegate (chapter 1) |
push_token_fcm | push_token_apns (hex of the APNs Data token) | platform token type; the deliverer already resolves both identifiers (chapter 7) |
Bundle overloads on push.parse/trackOpen | [AnyHashable: Any] userInfo overloads | UNNotification payload shape (chapter 7) |
SharedPreferences, filesDir | UserDefaults (its own com.optima.sdk suite, not .standard — the SDK never writes into your app's defaults; it falls back to .standard, then to memory, only if that suite cannot be opened), Application Support/optima/outbox.jsonl | platform storage |
| Custom Tabs | SFSafariViewController | platform browser (chapter 6) |
WebView | WKWebView with a non-persistent WKWebsiteDataStore | platform web view (chapter 5) |
Jetpack Compose OptimaHost/OptimaSlot/OptimaRenderer | SwiftUI OptimaHost()/OptimaSlot("name")/OptimaRenderer protocol | platform UI (chapter 3) |
StateFlow/SharedFlow/Job | AsyncStream + .current value / Task | platform concurrency |
NSLock-free coroutine mutual exclusion (single-threaded dispatcher confinement) | Locked<T> (NSLock) around every mutable field shared between a caller thread and a Task | Swift Concurrency's Tasks hop threads more freely than a pinned coroutine dispatcher; explicit locking is the port that made every internal component's data race-free without adopting actor |
Everything else — event names, the omit-vs-[] consent declaration, 20 hits
/ 2 s batching, the 1s→2s→5s→15s→60s retry ladder, display rules,
mobile_inapp feedback, forms.load + hosted page, NBA's 404 kill switch,
the pixel-only tracker gate, storage key names (_optima_did,
_optima_consent, _optima_utm, _optima_sid, _optima_seen,
_optima_push_token) — is identical to Android on purpose.
Differences from the Web SDK
| Web SDK | iOS | Why |
|---|---|---|
page(), SPA history hooks (pushState/popState interception) | screen(name) + .optimaScreen/.auto UIViewController.viewDidAppear swizzle (chapter 3, chapter 2) | There's no browser History API on iOS. The SwiftUI modifier or the opt-in swizzle substitutes for SPA route-change detection; .manual (the default) is the escape hatch for apps whose navigation model doesn't line up with view-controller boundaries. |
Tracker script activation (data-optima-tracker DOM attribute), managed script/html/page tags | Only the gate (consent.can, consent.changes) and the pixel kind (chapter 4, chapter 3) | A managed script/html tag means "inject and run this JavaScript/markup on the page" — a concept with no equivalent on a native screen. A pixel (a plain GET request) has no such dependency and fires natively; script/html-kind rows are recognized but intentionally inert, logged once at debug ("managed script/html tags are not runnable on iOS; ignored"). |
web_personalization items | Dropped with one debug line (chapter 5) | Server-side template personalization rewrites DOM content that simply doesn't exist as a concept on a native screen. |
Cookies, cookieDomain config | UserDefaults only | iOS apps don't share a cookie jar with anything; there's no cross-subdomain identity problem for a cookieDomain setting to solve, and nothing analogous to configure. |
Global Privacy Control (navigator.globalPrivacyControl) | None on iOS | GPC is a browser-signal standard with no OS-level iOS equivalent to read. |
Google Consent Mode dataLayer reader (automatic gtag/dataLayer observation) | Manual consent.setGCM only; TCF is read automatically from IABTCF_TCString (chapter 4) | Google Consent Mode is a dataLayer/gtag.js convention specific to web pages; there's no equivalent runtime object to observe on iOS. TCF, by contrast, has a real cross-platform convention (IABTCF_TCString in UserDefaults on iOS, localStorage on web) that every compliant CMP SDK already writes to, so the SDK reads it the same way on every platform. |
codeMode inline/sandbox, CSP nonces, content:blocked event | htmlMode .webView/.off; HTML runs in an isolated WKWebView (chapter 2, chapter 5) | A browser page executing operator-authored script inline is a same-origin risk that CSP/sandboxing/nonces exist to contain. A native app has no "page origin" for that script to inherit in the first place — isolating it into its own WKWebView with a non-persistent data store achieves the same containment goal with a platform-native mechanism instead of a web-specific one, so there's no content:blocked event to fire — the isolation is structural, not something a customer's CSP can block. |
forms.render (a full native-DOM form renderer) | Not in this iteration — forms.load (headless) + the hosted page in SFSafariViewController (chapter 6) | Rendering an arbitrary field-driven form natively, matching a design system you don't control, is a materially larger surface than the rest of this SDK's UI (which mirrors a small, fixed set of content-item shapes). Headless loading plus a link to the same hosted page the Web SDK's own non-JS fallback uses covers every form today without committing to a native form-widget API prematurely. |
| A failed consent POST is not replayed | Undelivered consent.set requests are persisted and replayed at launch and on foreground (chapter 4) | A backgrounded or killed app routinely cuts the in-memory retry ladder short; a browser tab's decision is re-asked on the next visit, an app's is not. |
| — | push.* (setToken, parse, trackOpen) | Mobile push has no web equivalent in this SDK's scope — it exists purely because mobile apps need it, not because it mirrors something the Web SDK does differently. See chapter 7. |
What's identical
Event names and payloads, the omit-vs-[] consent declaration rule, the
tracking outbox batching numbers, the retry backoff ladder, the display
rule schema (trigger/frequency/dismissible/ttl_days/placement),
campaign mobile_inapp impression/click/dismiss feedback, the tracker-gate
consent.can pattern, and the wire contract itself (docs/oapi3_edge.yml/
contract/oapi3_edge.yml) — a change on any one side of that contract is a
change on all three. If you've integrated the Android or Web SDK before,
almost everything here should feel immediately familiar; these tables are
deliberately the complete list of what doesn't.