Skip to content
Optima docs
SDKsReact Native SDK

Consent

React Native SDK v1.2.0 — Consent

The store

Consent lives in one ConsentState, persisted under the key _optima_consent (via your Storage port — AsyncStorage by default) and hydrated once into memory at Optima.init. It survives process restarts; it does not survive reset() (see chapter 3), because a reset means a different person is now using the device, and their consent is not the previous person's to inherit.

interface ConsentState {
  v: 1;
  decisions: Record<string, boolean>;
  decidedAt?: number;
  bannerId?: string;
  policy?: Record<string, unknown>;
  lang?: string;
}

decidedAt !== undefined (isDecided(state), exported alongside ConsentState) is the load-bearing question: it's what beforeDecision = "buffer" gates on, and what the purposes declaration below keys off of. grantedPurposes(state) returns the sorted list of purposes currently true.

beforeDecision semantics

  • "buffer" (the default): every hit built before a decision exists still queues into the outbox, but the tracker's flush loop refuses to send while !isDecided(consent.get()) — hits pile up locally instead of leaving the device. The moment the first consent.set(...) call completes its local write, the queue is unblocked and everything queued so far ships in the next batch(es), each carrying the now-decided consent declaration.
  • "send": hits flush on the normal batch/coalesce schedule regardless of whether a decision exists yet. This is correct when your own consent UI gates calling the SDK at all (you don't Optima.init until consent is known), or under source = "cmp" (forced automatically — see chapter 2), where the CMP owns the decision and there's nothing of ours to buffer for.

identify is held too — in memory only, max 10 calls, sent at the first decision; held calls and buffered hits older than 30 minutes are dropped at the decision; reset() drops held identify calls.

Buffered hits are not exempt from the 200-entry outbox cap — a very long undecided period on a very active app can still lose the oldest hits, same as any other backlog.

The omit-vs-[] declaration rule

This is the single most important consent detail in the whole SDK, and it's identical across every Optima SDK. ConsentStore.declaration():

if (source === "optima" && isDecided(state)) out.purposes = grantedPurposes(state);
  • No decision yet (!isDecided): the purposes key is omitted entirely from the request's consent block (and if nothing else — no TCF string, no GCM map, no keys — is set either, the whole consent key is omitted from the request body). Omission means "consent is unknown," and the server treats an unknown purpose per its own configured default (which, depending on the purpose's collection-gate configuration, ranges from "allow" to "quarantine until known" — that policy lives entirely server-side and the SDK has no opinion on it).
  • A decision exists, everything rejected: purposes is sent as an explicit empty array []. This is not the same thing as omission — [] means "we asked, and the answer was no to everything," a materially different fact than "we haven't asked." Never conflate these two states in your own code if you touch ConsentState directly; the built-in banner and consent.set(...) already get this right — this note exists so a custom consent UI built against consent.set doesn't accidentally collapse them.

source = "cmp" never declares purposes at all, decided or not — see below.

The built-in banner

When consent.source = "optima" (the default) and the content engine's fetch for the implicit overlay slot (or any declared slot) returns a banner_consent-type item, <OptimaHost> renders it automatically via ConsentBannerRenderer — you don't need to write any banner UI yourself. It's a two-stage surface:

  1. Summary: title + body copy, and three actions — Accept all, Reject all, Manage.
  2. Manage (reached via the third button): a Switch row for every purpose in the item's purpose_details payload, seeded from the current decision (falling back to false if unset), plus a Save button. The toggle state shown is re-derived from purpose_details on every render (falling back to the current stored decision, then false) rather than frozen at first mount — a purpose_details list that grows across a refreshed item is picked up rather than silently dropped.

lang (a prop on OptimaHost/OptimaSlot) is your preferred banner language; it defaults to client.language, the detected device language (AppInfo.language, the same value context.language uses on every tracking hit). Copy resolves per-language from the item's payload.languages map with a fallback ladder, as actually implemented: your lang prop → the device language (e.g. "de-AT") → its primary subtag ("de") → "en" → whatever language key happens to exist first in the payload. Each of Accept all, Reject all, and Save calls consent.set(decisions, {bannerId: item.id, lang: resolvedLang, policy: item's policy block}) and then the renderer itself calls content.refresh() right after — so the very next content poll stops returning the banner (there's no separate "dismiss" call for a consent decision; posting the decision is what makes the banner go away).

If you're writing your own consent UI instead of using the built-in one, the recipe is: fetch the banner_consent item yourself (headless — chapter 5), render your own screen from its payload.languages/payload.purpose_details, and call consent.set(...) with the same shape. The meta.policy field exists precisely so a custom UI can still round-trip the policy-version metadata the server expects, without needing to understand its internal shape.

CMP passthrough

Two independent knobs, both covered from the config side in chapter 2:

  • TCF: unlike the Android/iOS SDKs, there is no native prefs file this pure-TypeScript SDK can read without native code — Android's IABTCF_TCString SharedPreferences and iOS's IABTCF_TCString UserDefaults convention both require a native bridge this SDK deliberately doesn't ship. Feed the string yourself, either directly:

    Optima.instance.consent.setTCF(myOneTrustSdk.getTCString());

    or, for live updates, inject a TcfSource port at init (see chapter 2 for the full example) — the SDK calls read() once at startup and subscribes to onChange if the port provides it, calling consent.setTCF internally either way. Common sources: OneTrust's or Didomi's React Native SDK, or your own bridge over a native CMP module.

  • GCM / arbitrary keys: manual only, same as Android/iOS — there is no Google Consent Mode dataLayer equivalent to read outside a web page. Call consent.setGCM({ad_storage: "denied", ...})/consent.setKeys({...}) yourself, typically from your CMP SDK's own consent-changed callback.

source = "cmp" additionally stops the SDK from declaring its own purposes array at all (see the omit-vs-[] section above — under "cmp" that whole branch of declaration() is skipped regardless of isDecided(state)), and diverts any served banner_consent item away from the built-in renderer into a plain content:item {slot, item} event for you to route into your CMP's own UI flow instead.

Gating third-party SDKs

consent.can(trackerName) plus consent.on(cb) is the pattern for deciding, at runtime, whether a third-party SDK you initialize yourself is allowed to run — the SDK doesn't (and can't) reach into another vendor's SDK and stop it, but it can tell you the answer so your own init code can decide. A typical Firebase Analytics gate, initialized lazily and re-checked on every consent change:

import analytics from "@react-native-firebase/analytics";
import { Optima } from "@optima/react-native";

let initialized = false;

function applyGate(): void {
  const allowed = Optima.instance.consent.can("firebase_analytics");
  if (allowed && !initialized) {
    void analytics().setAnalyticsCollectionEnabled(true);
    initialized = true;
  } else if (!allowed && initialized) {
    void analytics().setAnalyticsCollectionEnabled(false);
    // Firebase keeps running once initialized; disabling collection is the
    // available lever — a true "unload" isn't offered by that SDK either.
  }
}

function startAnalyticsGate(): () => void {
  // `consent.on` only fires on a FUTURE "consent:change" — unlike `on("ready", ...)`,
  // it is not replayed to a late subscriber. A decision already made in a previous
  // session (persisted consent) would otherwise never get evaluated until the next
  // change, which may never come — so check once at startup too.
  applyGate();
  return Optima.instance.consent.on(() => applyGate());
}

"firebase_analytics" here must be a name registered in the Optima console's tracker inventory (edge_trackers, the same table the SDK reads via GET /edge/v1/trackers), with its purpose pointed at whichever consent purpose should gate it. consent.can returns false (fail-closed) for any name that isn't in that inventory or hasn't loaded yet — a typo in the name you pass silently gates the SDK off forever, so double-check it against the console.

Revocation

consent:revoked {purposes} fires whenever a consent.set(...) call flips a previously-true purpose to false. A running third-party SDK cannot generally be unloaded — most native SDKs have no API to un-initialize already-started native code, background threads, or file handles they opened. The event is your signal to do whatever your SDK's own "stop/disable" API offers (as in the Firebase example above); the app is the one that decides what "stop" means for each vendor it embeds — the platform SDK itself has no opinion on what compliance requires you to do in response.

reset() on logout

reset() clears _optima_consent back to a fresh, undecided ConsentState as one of its first steps, and emits consent:change with that fresh state. On a shared/kiosk device, call it on every logout — the next person who picks up the device should see the consent banner again, not inherit the previous person's decision. Vendor-level TCF/GCM/keys set via setTCF/setGCM/setKeys deliberately survive reset() — they are the CMP's state, not the SDK's, and a CMP typically re-asserts its own state independently of an Optima-side reset. See chapter 3 for the full ordering of what else reset() clears.

On this page