Skip to content
Optima docs
SDKsReact Native SDK

Differences from the Web and Android SDKs

React Native SDK v1.2.0 — Differences from the Web and Android SDKs

The React Native SDK follows the Web SDK and the Android SDK as closely as the platform allows — same event names, same wire contract, same consent semantics. Where it diverges, it's a deliberate consequence of not running inside a browser DOM, of having no native code of its own, or of an iteration boundary for this first release. These two tables are the authoritative list; every row is discussed in more depth in the chapter its right-hand column links to.

vs. the Web SDK

Web SDKReact NativeWhy
page(), SPA history hooks (pushState/popState interception)screen(name) + navigation.onReady/onStateChange for React Navigation, useScreenTracking(pathname) for Expo Router (ch. 3, ch. 1)There's no browser History API in a native app. Both router-agnostic helpers substitute a screen-focus walk for SPA route-change detection; a plain screen() call is always available as the manual escape hatch.
Tracker script activation (data-optima-tracker DOM attribute), managed script/html/page tagsOnly the gate (consent.can, consent.on) and the pixel kind (ch. 4)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, logging one debug line the first time either is encountered (never again after that); page-kind rows are simply skipped with no log at all.
web_personalization itemsDropped with one debug line (ch. 5)Server-side template personalization rewrites DOM content that simply doesn't exist as a concept on a native screen.
Cookies, cookieDomain configThe Storage port (AsyncStorage by default)A React Native app doesn't share a cookie jar with anything; there's no cross-subdomain identity problem for a cookieDomain setting to solve.
Global Privacy Control (navigator.globalPrivacyControl)NoneGPC is a browser-signal standard with no OS-level or React Native equivalent to read.
Google Consent Mode dataLayer reader (automatic gtag/dataLayer observation); TCF read automatically via the IAB window.__tcfapi("addEventListener", 2, cb) command queue every compliant CMP exposes on the pageManual consent.setGCM only; TCF is also manual (consent.setTCF, fed from your CMP's RN SDK) or via an injected tcfSource port (ch. 4)Google Consent Mode is a dataLayer/gtag.js convention specific to web pages. __tcfapi is a window-global JavaScript API a page's CMP script installs — there is no equivalent global to call into on React Native (Android/iOS instead have a real cross-platform convention: a native prefs file every compliant CMP SDK writes to, which this pure-TypeScript SDK cannot read without native code — see the Android-comparison table below for that version of the gap).
codeMode inline/sandbox, CSP nonces, content:blocked eventdisplay.htmlMode "webview"/"off"; HTML runs in an isolated react-native-webview (ch. 2, ch. 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 — isolating it into its own WebView (no shared cookies/storage with the host app, served as an inline about:blank document rather than a real URL) achieves the same containment with a platform-native mechanism, so there's no content:blocked event to fire.
forms.render (a full native-DOM form renderer)<OptimaForm> — a minimal field-driven renderer, plus headless forms.load/submit and the hosted page via Linking.openURL (ch. 6)Unlike the Android SDK (below), this release does ship a native renderer — a small, fixed set of field types (TextInput/Switch/an option list) rather than an arbitrary DOM form, matching the same small-and-fixed philosophy as the rest of this SDK's ui entry.
—push.* (setToken, parse, trackOpen)Mobile push has no web equivalent in this SDK's scope — it exists purely because mobile apps need it. See chapter 7.

vs. the Android SDK

Android SDKReact NativeWhy
Optima.init(context, config) synchronous; Ready replayedawait Optima.init(config) — hydration of persisted state is async (AsyncStorage); calls made before it resolves are queued in order and replayed once the runtime is ready (ch. 3, spec amendment 3)Kotlin can open SharedPreferences synchronously; AsyncStorage.multiGet is inherently async. Making Optima.instance one stable object throughout (rather than "the client, once it exists") means hooks and modules can capture it once and never race init.
screenTracking = AUTO via ActivityLifecycleCallbacksManual screen() + navigation.onReady/onStateChange for React Navigation, useScreenTracking(pathname) for Expo Router (ch. 1)There's no single "screen boundary" primitive across React Native's navigation ecosystem the way an Android Activity is one — a router-agnostic helper per router family replaces one universal automatic mode.
Job / suspendPromiseIdiomatic per platform; identify, consent.set, and flush all resolve once the first network attempt settles, matching the Job/suspend contract's own semantics.
StateFlow / SharedFlowSlotHandle {get(), subscribe(cb)} + on(); ./ui hooks wrap both via useSyncExternalStore (ch. 3)React's own reactive-state primitive is useSyncExternalStore, not a Flow — SlotHandle is shaped to feed it directly, and on() is a plain subscribe/unsubscribe pair rather than a Flow type.
App id/version from PackageManagerconfig.app → expo-application → react-native-device-info → "unknown" with one warning (ch. 1)There's no single first-party API for this in React Native; the fallback chain covers both the Expo-managed and bare-RN ecosystems without requiring either as a hard dependency.
TCF read automatically from IABTCF_TCString SharedPreferencesNo native prefs access without native code: consent.setTCF(...) (fed from your CMP's RN SDK) or an injected tcfSource port (ch. 4)This SDK is deliberately pure TypeScript with no native module of its own (see the design spec's architecture decision) — reading a native prefs file is exactly the kind of native code that rules out.
Custom Tabs for hosted pages/linksLinking.openURL (wrap expo-web-browser or an in-app-browser library yourself for Custom-Tabs-style chrome) (ch. 6)Linking is the cross-platform primitive available without adding a peer; a Custom-Tabs-equivalent experience is one library import away if you want it, and the SDK doesn't force that choice on you.
Compose OptimaHost/OptimaSlot, Material theme (OptimaTheme.fromMaterial())React <OptimaHost>/<OptimaSlot>, OptimaTheme with a fixed default palette, no Material coupling (ch. 3)There is no single dominant design system across React Native apps the way Material is on Android — a flat, explicit palette you override is more portable than assuming any particular component library.
No native form renderer (headless forms.load + Custom Tab only)<OptimaForm> minimal renderer in ./ui (ch. 6)The reverse of the Web-SDK row above: this release adds the small renderer Android's own guide explicitly deferred, since React Native's fixed field-type set (TextInput/Switch/options) is a small enough surface to commit to now.
FCM-only token (push_token_fcm)Platform-defaulted token key (push_token_fcm/push_token_apns from Platform.OS); payloads from either @react-native-firebase/messaging or expo-notifications (ch. 7)A single codebase targets both iOS and Android, so the token key has to follow the platform rather than being fixed to one push provider; push.parse also accepts expo-notifications' typed buttons field, not just FCM's all-string JSON payload.
push.parse(Bundle) overloadPlain object onlyNo Bundle equivalent exists in React Native; every push library already hands you a plain JS object.

What's identical

Everything not in either table above is the same on purpose: track/ identify/reset/deviceId/flush/the event names and payloads, the consent omit-vs-[] declaration rule, the outbox batching numbers (20 hits / 2s coalesce, 200-entry cap), the retry backoff ladder (1s/2s/5s/15s/60s, Retry-After honoured), the display rule schema (trigger/frequency/dismissible/ttl_days/placement), the app://<appId>/<screen> URL convention, campaign mobile_inapp impression/click/dismiss feedback, the optima-action:// HTML bridge contract (§4 amendment 1 — ported from Android's HtmlBridge.kt verbatim, so operator HTML authored for any mobile SDK works unchanged on this one), the tracker-gate consent.can pattern including the persisted-ETag inventory (this SDK closes a parked Android TODO by persisting {etag, entries} together across process restarts), and the wire contract itself (docs/oapi3_edge.yml/contract/oapi3_edge.yml — a change on one side of that contract is a change on all three SDKs). If you've integrated the Web or Android SDK before, almost everything here should feel immediately familiar; these tables are deliberately the complete list of what doesn't.

On this page