Skip to content
Optima docs
SDKsReact Native SDK

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

KeyTypeDefaultMeaning
keystring (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.
endpointstring (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.
debugbooleanfalseEnables 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 }detectedOverrides 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.
portsPartial<Ports>platform defaultsInjects 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:

  1. beforeDecision is silently overridden to "send" no matter what you wrote — see resolveConfig's own comment: "source=cmp hands the decision to the CMP: buffering would wait for a decision that is not ours to make."
  2. The SDK stops declaring its own consent state (consent.set, consent.get().decisions) as the purposes array on outgoing requests. It still merges in whatever you feed consent.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.

On this page