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 firstconsent.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'tOptima.inituntil consent is known), or undersource = "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): thepurposeskey is omitted entirely from the request'sconsentblock (and if nothing else — no TCF string, no GCM map, no keys — is set either, the wholeconsentkey 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:
purposesis 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 touchConsentStatedirectly; the built-in banner andconsent.set(...)already get this right — this note exists so a custom consent UI built againstconsent.setdoesn'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:
- Summary: title + body copy, and three actions — Accept all, Reject all, Manage.
- Manage (reached via the third button): a
Switchrow for every purpose in the item'spurpose_detailspayload, seeded from the current decision (falling back tofalseif unset), plus a Save button. The toggle state shown is re-derived frompurpose_detailson every render (falling back to the current stored decision, thenfalse) rather than frozen at first mount — apurpose_detailslist 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_TCStringSharedPreferences and iOS'sIABTCF_TCStringUserDefaultsconvention 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
TcfSourceport atinit(see chapter 2 for the full example) — the SDK callsread()once at startup and subscribes toonChangeif the port provides it, callingconsent.setTCFinternally 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
dataLayerequivalent to read outside a web page. Callconsent.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.