Configuration
React Native SDK v1.2.0 — Configuration
OptimaConfig is passed once, to Optima.init(config), and is resolved
immutably at that point (resolveConfig, src/config.ts) — there is no way
to change endpoint or display.htmlMode mid-run short of a full process
restart:
await Optima.init({
key: "oek_shop_a1b2c3",
endpoint: "https://edge.shop.example",
debug: __DEV__,
app: { id: "com.shop.app", version: "3.2.0" },
consent: { beforeDecision: "buffer", source: "optima" },
display: { htmlMode: "webview" },
ports: { storage: myMmkvStorage },
});Keys
| Key | Type | Default | Meaning |
|---|---|---|---|
key | string (required) | — | The Edge SDK key (oek_...). Validated non-blank at init time (OptimaConfig.key is required thrown inside the guard, surfaced as Optima.init failed; SDK disabled); sent as the X-Edge-Key header on every request. See The SDK key below. |
endpoint | string (required) | — | The base URL of your Optima Edge gateway, e.g. https://edge.shop.example. Must match /^https?:\/\/\S+$/ (validated at init time: OptimaConfig.endpoint must be an absolute http(s) URL); a trailing slash is stripped. Every request is <endpoint>/edge/v1/... — nothing else is ever called. |
debug | boolean | false | Enables logger.debug output (the default ConsoleLogger gates console.log on this; console.warn always fires regardless). Leave off in production builds — it is a log-verbosity switch only, never a data-plane one. |
app | { id: string; version: string } | detected | Overrides the AppInfo port's auto-detection (expo-application → react-native-device-info → "unknown"/"unknown" with one warning). Feeds context.url (app://<id>/<screen>) and the ua string on every hit. |
consent.beforeDecision | "buffer" | "send" | "buffer" | "buffer": hits queue in the on-disk outbox but the tracker's flush loop refuses to send while !consent.get().decided — the first consent.set(...) call unblocks the queue. "send": hits flush on the normal batch/coalesce schedule regardless of whether a decision exists. Forced to "send" automatically whenever consent.source = "cmp" — see The source = "cmp" rule below. |
consent.source | "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 surfaces as a plain content:item event instead of the built-in banner, and you drive consent entirely through consent.setKeys/setGCM/setTCF fed from your CMP SDK (or an injected tcfSource port — see Injecting ports below). |
display.htmlMode | "webview" | "off" | "webview" | Governs only unstructured content items (raw operator-authored HTML/CSS/JS). "webview": ./ui's HtmlRenderer renders them in an isolated react-native-webview (JavaScript on, no shared cookies or DOM storage — see chapter 5); automatically downgraded to "off" at init if the react-native-webview peer isn't installed. "off": unstructured items never become a Presentation — they surface as content:item events instead, and the built-in renderers skip them. |
ports | Partial<Ports> | platform defaults | Injects any subset of {storage, http, clock, lifecycle, tcfSource, appInfo, logger, links} — see chapter 3 for the full port interfaces and Injecting ports below for two worked examples. |
The source = "cmp" rule, once more explicitly
Setting consent.source = "cmp" is a one-way toggle on two independent
behaviours, both fixed for the life of the resolved config:
beforeDecisionis silently overridden to"send"no matter what you wrote — seeresolveConfig's own comment: "source=cmphands 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, 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 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 track("screen_view", name, ...) under the
hood (see 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 event's
dropped array, never a hard error). This is the same rule the Web and
Android/iOS SDKs' screen_view/page_view categories follow. See
chapter 1 for the recommended
mapping table.
Injecting ports
Every platform touch is behind a small interface in src/ports.ts, defaulted
in src/platform/ and overridable per key via config.ports. Two common
reasons to inject one:
MMKV instead of AsyncStorage — implement Storage (getMany, set,
remove, all Promise-returning):
import { MMKV } from "react-native-mmkv";
import type { Storage } from "@optima/react-native";
const mmkv = new MMKV({ id: "optima" });
const mmkvStorage: Storage = {
async getMany(keys) {
const out: Record<string, string | null> = {};
for (const k of keys) out[k] = mmkv.getString(k) ?? null;
return out;
},
async set(key, value) { mmkv.set(key, value); },
async remove(key) { mmkv.delete(key); },
};
await Optima.init({ key, endpoint, ports: { storage: mmkvStorage } });A CMP's TCF string over tcfSource — implement TcfSource (read()
returning Promise<string | null>, and an optional onChange(cb) for live
updates):
import type { TcfSource } from "@optima/react-native";
function tcfSourceFromMyCmp(cmp: MyCmpSdk): TcfSource {
return {
read: async () => cmp.getTCString() ?? null,
onChange(cb) {
const sub = cmp.onConsentUpdate((tc) => cb(tc ?? null));
return () => sub.remove();
},
};
}
await Optima.init({ key, endpoint, ports: { tcfSource: tcfSourceFromMyCmp(myCmp) } });See chapter 4 for why a tcfSource port
exists at all on React Native (there is no native prefs file the SDK can read
without native code, unlike the Android/iOS SDKs' automatic IABTCF_*
reads — this is the documented, deliberate difference; see
chapter 8).
Any port you don't override falls back to the platform default described in chapter 3 — you never need to supply all eight to override one.