Content
React Native SDK v1.2.0 — Content
Slots and placement
Content is organized into named slots — arbitrary strings your app
defines, matching whatever the operator targets in the console (a slot name
like "homepage_hero" or "checkout_upsell"). Declare a slot in two ways:
ui: drop<OptimaSlot name="homepage_hero" />where you want inline content to render, and put one<OptimaHost />near your app's root to catch overlay-placement content (banners, cards) from every slot, plus the implicitcontent.overlaySlot("__overlay") used by items with no explicit slot.- Headless: call
Optima.instance.content.slot("homepage_hero")yourself, and render the returnedSlotHandlehowever you like — see Headless use.
Every Presentation carries a placement: "inline" (render it where you
declared the slot — this is what OptimaSlot draws) or "overlay" (render
it floating above everything — this is what OptimaHost draws). The
server's display.placement field decides this per item; when it's absent,
the SDK defaults to "overlay".
The no-slot caveat
An inline-placement item whose slot has no corresponding OptimaSlot
anywhere in your tree renders nowhere. Declaring the slot via
content.slot(name) headlessly and then never rendering its presentations
has the same effect — the item is fetched, counted in content:loaded, and
then simply has nowhere to go. This is by design (there's no implicit
fallback location for an inline item), but it's an easy trap when a new slot
is targeted in the console before the corresponding OptimaSlot ships in an
app update — the item just silently never appears, with no error anywhere.
If you see a content:loaded {slot, count > 0} event but nothing on screen,
this is the first thing to check.
Screens and URLs
Every screen(name) call sets the SDK's notion of "current screen," which
feeds two things: the screen_view tracking hit
(chapter 3) and
every content fetch's screen/url query parameters. The URL follows a
fixed convention: app://<appId>/<screen> — for example,
app://com.example.shop/ProductDetail. This exists so the console's
existing URL-glob targeting (built for the Web SDK's real page URLs) stays
meaningful on mobile without a separate targeting model: an operator can
write a URL pattern like app://com.example.shop/Product* and it matches
every screen name starting with Product, exactly the way
https://shop.example/product/* would match web pages.
Two kinds of content targeting exist server-side and both arrive through
this one mechanism: operator-authored items matched by URL glob against
this app:// URL, and campaign mobile_inapp items matched by the
literal screen name (not a glob) — you don't need to do anything different
for either kind, the same slot(name) call surfaces both.
A screen change drops every declared slot's stored ETag. The gateway's
ETag used to be a config stamp, not a per-screen value (on gateways before 2026-10) — without this, a 304 Not Modified for the new screen could have resurrected the old screen's
already-committed items. refresh() on the same screen still sends
If-None-Match and can legitimately get a 304 (nothing changed) — only an
actual screen() call clears the cached tag. Since the 2026-10 gateway the content ETag also covers the served item set, so this is a
conservative choice rather than a correctness requirement.
display rules
Every structured content item's payload.display object is parsed into a
DisplayRule and applied verbatim, field by field:
| Field | Values | Behaviour |
|---|---|---|
trigger.on | load | delay | event | load: shown as soon as it resolves from the fetch. delay: shown after trigger.delay_ms milliseconds (a timer fenced by the same per-slot generation counter as the fetch itself, so a superseded fetch's pending timers never fire). event: shown the next time track(category) is called locally with category == trigger.event. scroll and exit (web-only concepts with no React Native equivalent) fold to load — there's no DOM to scroll or a tab to exit, so the SDK treats them as "show immediately" rather than dropping the item. |
frequency | always | session | once | {per_days: N} | always: shown every time it's returned. session: shown once per app process (in-memory only, reset by reset() and process death). once: shown once ever, remembered in _optima_seen. {per_days: N}: shown at most once every N days. |
dismissible | true | false | absent | Whether a close control is rendered. Absent falls back to the item's campaign display block (dismissible there) if present, then to "true for overlay, false for inline." |
ttl_days | integer | absent | After a dismiss, the item is suppressed for this many days even if its frequency would otherwise allow it again — dismissal is a stronger, time-bounded "no" than the frequency rule alone. Absent ttl_days on a dismissed item suppresses it permanently (never shown again on this device) rather than falling back to no suppression — a dismiss with no configured TTL is treated as "forever," not "no additional restriction." |
placement | inline | overlay | absent | See Slots and placement above; absent defaults to overlay. |
position / style | top/bottom; card/bar/modal | Cosmetic — read by the built-in renderers (OptimaHost picks its top/bottom group from position; InAppRenderer/HtmlRenderer pick their card/bar/modal chrome from style). |
Seen/dismiss memory (once, per_days, ttl_days) is stored per item id in
_optima_seen; the session rule additionally keeps an in-memory set that's
cheaper to check and doesn't need to survive a restart. A fresh fetch that
genuinely changes a slot's contents resets that slot's impression dedup
memory specifically — so an always-frequency item served again after a
real content change reports a new impression locally (the engine will
call content.report(..., "impression") again), rather than being silently
deduped forever against a Presentation object that no longer exists.
Dismiss/shown-once memory is untouched by this — only the impression
dedup resets.
There is a second, independent dedup layer past that point: the delivery
token a campaign item carries is deduped by the reporter for the life of
the process, never reset by a fresh fetch or a slot-level dedup reset — so
if the very same campaign entitlement (the same token) is re-served after
a refresh, the engine calls content.report again as described above, but
the actual POST /edge/v1/content/events impression/dismiss event for that
token is only ever sent once per process (a click is never deduped this
way). This only matters for a re-served campaign item sharing an identical
token; an operator (non-campaign) item has no token and isn't affected.
Campaign mobile_inapp items and feedback
An onsite-campaign item (origin === "campaign", isCampaign(item) === true) is a per-profile content entitlement the campaign engine created
for this specific device — served once, feedback-tracked precisely:
- Impression:
RenderPresentationreports it once, on the presentation's first mount — there is no viewport-based dwell timer on React Native (this is a documented parked item, seeTODO.md; the Android/iOS SDKs measure "at least 50% visible for 1 second," this SDK reports as soon as the component renders). If you're rendering headlessly, you own whatever impression timing you want before callingcontent.report(presentation, "impression")— note the parameter is thePresentation(SlotHandle.get()'s element), not the rawContentItem. - Click:
content.report(presentation, "click"), fired by the built-in renderers' CTA/link. If the item's campaign display carriesstop_on_click = true, the item is also immediately removed from its slot's list — a "one click and it's gone" surface. - Dismiss:
content.report(presentation, "dismiss"), which also removes it from the list and starts itsttl_dayssuppression clock.
max_impressions (part of the campaign display block) is enforced
server-side, not locally — the SDK reports every impression it sees; the
campaign engine, not the device, is the source of truth for "this
entitlement has been shown enough times," and stops serving the item once
its budget is spent. The device-local campaignDisplay fields you do see
(dismissible, stopOnClick) are the ones the SDK itself needs to act on
immediately without a round trip.
Custom renderers
For your own structured content types, register a React component matching
OptimaRenderer — typically once, right after Optima.init:
import { Optima } from "@optima/react-native";
import type { OptimaRenderer } from "@optima/react-native/ui";
const ProductCarousel: OptimaRenderer = ({ presentation, actions, theme }) => {
const skus = (presentation.item.payload?.skus as string[] | undefined) ?? [];
return (
<Carousel
skus={skus}
onPress={(sku) => { actions.onClick(); actions.openUrl(`app://com.shop.app/Product/${sku}`); }}
/>
);
};
Optima.instance.content.register("product_carousel", ProductCarousel);Once registered, both OptimaHost and OptimaSlot pick it up automatically
via content.rendererFor(type) — you never call it directly.
RenderPresentation reports the impression on mount for you (unlike the
built-in banner_consent renderer, which manages its own lifecycle); an
unregistered structured type surfaces as a content:item event instead
(see chapter 3), so registering nothing for a
type you don't care about is a safe default, not a broken one. This includes the operator content types inline and custom: register a renderer for them, or handle content:item.
The built-in consent banner hides as soon as the visitor decides, and stays hidden for the rest of the process while the gateway catches up. A banner whose id was decided stays hidden for the rest of the app process even if re-served with the same id; a re-ask under a NEW banner id shows immediately; reset() clears it.
Headless use
Skip @optima/react-native/ui entirely and drive content yourself with
content.fetch(slot) (one-shot, no rules applied — you own targeting,
frequency, and placement) or content.slot(name) (declared, rules applied,
still no rendering) plus manual content.report(...) calls for whatever you
display. This is the right choice for a screen your own design system fully
owns, a game-engine surface, or react-native-web (untested, but the
headless core has no React Native-specific dependency beyond its platform
ports).
Unstructured HTML
Operator-authored raw HTML/CSS/JS items (format === "unstructured") render
in an isolated react-native-webview when display.htmlMode = "webview"
(the default): incognito, sharedCookiesEnabled={false},
thirdPartyCookiesEnabled={false}, domStorageEnabled={false},
originWhitelist={["about:blank"]}, JavaScript on. The page is served as an
inline source={{html, baseUrl: "about:blank"}} — never a real URL — so
there is no origin for it to inherit cookies or storage from, and no
navigation destination other than the reserved bridge scheme below or a
link you explicitly allow through openUrl.
A tap on a plain <a href> (no data-link needed) is bridged exactly like
data-link: the bootstrap turns it into optima-action://link?url=..., so
it reports a click and then goes to RenderActions.openUrl. Every other
navigation inside the WebView (a script redirect, a meta refresh, an iframe)
is cancelled silently and never opened. openUrl refuses data:, blob:,
intent:, about:, file:, content:, javascript: and vbscript: URLs
and scheme-less URLs.
The bridge is authenticated. Every optima-action:// URL the bootstrap sends
carries a nonce minted for that render, so an embedded third-party frame
(video, map, ad) cannot forge a close, a link or a height. The item's own
scripts are not kept out by the nonce (it is visible in the bridge iframes
they share a document with); instead a link opens only within 1.5 s of a
touch anywhere on the item, and clicks dispatched by script are ignored. While
a screen reader is on — on Android, any accessibility service — the touch
requirement is waived, because those activations are not touches. iOS Switch
Control, Voice Control and Full Keyboard Access give React Native no signal,
so those users cannot open bridged links yet (TODO.md). Render HTML only from
sources you trust.
Declarative actions (the cross-SDK bridge)
An item needs no bespoke integration to close itself, report a link click,
or report its height — the same optima-action:// bridge contract the
Android and iOS SDKs use (internal/*/HtmlBridge, dated 2026-09-21;
src/ui/renderers/html_bridge.ts on this SDK). A bootstrap script is
injected once, ahead of the operator's own HTML, that installs one
capturing click listener and resolves the nearest element (the clicked
element or an ancestor) carrying either attribute:
data-actiontype="close"— dismisses the item through the normal dismiss path: adismissis reported for campaign (token-bearing) items, the dismiss memory (ttl_daysrule) is recorded for every item, campaign or not, and the presentation is removed so the slot or overlay host stops drawing it.data-link="<url>"— reports aclickand opens the URL throughRenderActions.openUrl, with the same scheme rules as a plain link.
close wins when both attributes sit on the same element. The script talks
to the SDK by navigating a hidden, invisible iframe to
optima-action://close, optima-action://link?url=…, or
optima-action://height?h=…; HtmlRenderer's
onShouldStartLoadWithRequest intercepts and cancels every one of these —
the WebView itself never actually navigates, and no injectedJavaScript
bridge object or onMessage channel is ever exposed to the page.
<div class="promo">
<button data-actiontype="close" aria-label="Close">×</button>
<p>Spring sale — 20% off</p>
<a href="#" data-link="https://shop.example/sale">Shop now</a>
</div>Operator HTML authored for the Web, Android, or iOS SDKs works unchanged here — it's the same contract on every platform.
Auto-height
The WebView starts at a small default height (120) and resizes as the page
reports. The bootstrap measures body's box plus its vertical margins — not
documentElement.scrollHeight, which is at least the viewport height and
would lock a too-tall view in place — via a ResizeObserver on body (with
load/resize events as a fallback for older engines), reporting through
the same optima-action://height?h=<px> bridge call whenever the measured
height changes.
An item without a <!DOCTYPE> gets <!DOCTYPE html> prepended (after the
bootstrap <script> tag, before whatever content follows): in quirks mode,
body stretches to the viewport, which would make the measured height
follow the view instead of the content. Author the item as you would for any
other Optima SDK — it renders in standards mode either way.
Set display.htmlMode = "off" to disable this renderer entirely — or leave
react-native-webview uninstalled, which achieves the same thing
automatically (with a one-time warning at init; see
chapter 1). An unstructured item then
never becomes a Presentation: it is emitted as a content:item {slot, item} event so you can render (or ignore) it yourself. There is no "render
it, but without JS" middle setting. Because it never becomes a
Presentation, an htmlMode = "off" item also bypasses the SDK's
frequency/dismiss memory — same as an unregistered structured type — so
avoiding re-showing it is on your own code if that matters for your UI.
web_personalization
Items of type web_personalization (server-side rendered template
personalization, a purely web concept — it depends on rewriting DOM content
that doesn't exist on a native screen) are dropped, silently as far as
your app's UI is concerned, with a single debug-level log line the first
time it happens per process ("web_personalization items are not applicable on mobile; dropped"). They are excluded from content:loaded's count. If
you're targeting the same slot from both web and mobile, expect
web_personalization items to simply never reach a React Native device —
there is nothing to configure to change this, and nothing about the SDK is
broken if you never see one come through.
Theming
OptimaTheme ({surface, onSurface, primary, onPrimary, muted, radius},
defaultTheme exported from ./ui) is the flat colour/shape palette every
built-in renderer styles itself with — pass your own to OptimaHost,
OptimaSlot, and OptimaForm to match your app's design system; there is no
Material/Paper/NativeBase coupling to fight. See
chapter 3 for the exact
shape.