Skip to content
Optima docs
SDKsiOS SDK

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

AndroidiOSWhy
screenTracking = AUTO by default via ActivityLifecycleCallbacksdefault .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_fcmpush_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 overloadsUNNotification payload shape (chapter 7)
SharedPreferences, filesDirUserDefaults (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.jsonlplatform storage
Custom TabsSFSafariViewControllerplatform browser (chapter 6)
WebViewWKWebView with a non-persistent WKWebsiteDataStoreplatform web view (chapter 5)
Jetpack Compose OptimaHost/OptimaSlot/OptimaRendererSwiftUI OptimaHost()/OptimaSlot("name")/OptimaRenderer protocolplatform UI (chapter 3)
StateFlow/SharedFlow/JobAsyncStream + .current value / Taskplatform concurrency
NSLock-free coroutine mutual exclusion (single-threaded dispatcher confinement)Locked<T> (NSLock) around every mutable field shared between a caller thread and a TaskSwift 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 SDKiOSWhy
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 tagsOnly 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 itemsDropped 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 configUserDefaults onlyiOS 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 iOSGPC 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 eventhtmlMode .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 replayedUndelivered 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.

On this page