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 SDK | React Native | Why |
|---|---|---|
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 tags | Only 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 items | Dropped 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 config | The 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) | None | GPC 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 page | Manual 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 event | display.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 SDK | React Native | Why |
|---|---|---|
Optima.init(context, config) synchronous; Ready replayed | await 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 ActivityLifecycleCallbacks | Manual 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 / suspend | Promise | Idiomatic per platform; identify, consent.set, and flush all resolve once the first network attempt settles, matching the Job/suspend contract's own semantics. |
StateFlow / SharedFlow | SlotHandle {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 PackageManager | config.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 SharedPreferences | No 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/links | Linking.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) overload | Plain object only | No 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.