Content
Android SDK v1.4.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:
- Compose: drop
OptimaSlot("homepage_hero")where you want inline content to render, and put oneOptimaHost()near your app's root to catch overlay-placement content (dialogs, bottom cards) from every slot, plus the implicit__overlayslot used by items with no explicit inline placement. - Headless: call
optima.content.slot("homepage_hero")yourself, and render the returnedStateFlow<List<Presentation>>however 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 composition renders nowhere. Declaring the slot via
content.slot(name) headlessly and then never rendering its StateFlow
has the same effect — the item is fetched, counted in ContentLoaded, 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 ContentLoaded(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://<package>/<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. $context.url in the console's category-mapping and
report tooling reads this same value.
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.
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. event: shown the next time track(category) is called locally with category == trigger.event. scroll and exit (web-only concepts with no Android 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. A pending delay/event trigger survives a 304 Not Modified revalidation (every screen change) and is cancelled only when a fetch actually replaces the slot. |
frequency | always | session | once | {per_days: N} | always: shown every time it's returned. session: shown once per app session (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 | 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. |
placement | inline | overlay | absent | See Slots and placement above; absent defaults to overlay. |
position / style | top/bottom; card/bar/modal | Cosmetic — read by the Compose renderers (OptimaHost picks its alignment from position; InAppRenderer picks AlertDialog/full-width Surface/card Surface 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 (not a 304 Not Modified) resets that
slot's impression dedup memory specifically — so an always-frequency item
served again after a real content change reports a new impression, rather
than being silently deduped forever against a Presentation instance that
no longer exists. Dismiss/shown-once memory is untouched by this — only the
impression-reporting dedup resets.
Campaign mobile_inapp items and feedback
An onsite-campaign item (origin == "campaign", isCampaign == true) is a
per-profile content entitlement the campaign engine created for this
specific device — served once, feedback-tracked precisely:
- Impression: reported once an item has been on screen for at least
50% visible for 1 second — the Compose renderers (
Impression.kt'sreportImpressionmodifier) measure this for you on every built-in renderer; if you're rendering headlessly, you own this timing check yourself before callingcontent.report(item, ContentAction.IMPRESSION). - Click:
content.report(item, ContentAction.CLICK), fired by the built-in renderers' CTA button. If the item's campaign display carriesstop_on_click = true, the item is also immediately removed from its slot's flow — a "one click and it's gone" surface. - Dismiss:
content.report(item, ContentAction.DISMISS), which also removes it from the flow 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, implement OptimaRenderer and
register it — typically once, right after Optima.init:
OptimaRenderer is a fun interface whose single method is itself marked
@Composable — write it as an explicit anonymous object rather than a
trailing-lambda SAM conversion, so there's no ambiguity about the lambda
being treated as a composable function type:
Optima.instance.content.register("product_carousel", object : OptimaRenderer {
@Composable
override fun Render(presentation: Presentation, actions: RenderActions) {
val skus = presentation.item.payload?.optJSONArray("skus")
LaunchedEffect(presentation.item.id) { actions.onImpression() }
ProductCarousel(skus, onProductClick = { actions.onClick(); actions.openUrl("app://com.example.shop/Product/${it}") })
}
})Once registered, both OptimaHost and OptimaSlot pick it up automatically
via content.rendererFor(type) — you never call it directly. An
unregistered structured type surfaces as a plain ContentItem event instead
(see chapter 3), so registering nothing for a
type you don't care about is a safe default, not a broken one.
Headless use
Skip optima-sdk-compose 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 Views-based app, a game engine
surface, or any UI that the Compose renderers' Material3 styling wouldn't
fit anyway.
Unstructured HTML
Operator-authored raw HTML/CSS/JS items (format == "unstructured", the Web
SDK's unstructured items) render in an isolated WebView when
display.htmlMode = HtmlMode.WEBVIEW (the default). JavaScript is enabled;
everything the renderer can turn off for that one WebView, it does:
domStorageEnabled = false, allowFileAccess = false,
allowContentAccess = false, setGeolocationEnabled(false), and
CookieManager.setAcceptThirdPartyCookies(webView, false).
What it deliberately does not do is block first-party cookies. The only API
for that, CookieManager.setAcceptCookie(false), is process-global — it
would silently break every other WebView your app owns, including a logged-in
one, and that is not a decision a content renderer gets to make. Android offers
no per-WebView cookie switch, so treat rendered HTML as sharing the app's
WebView cookie jar for first-party cookies, and keep that in mind when an
operator authors an item that loads third-party resources.
Navigation inside the WebView is classified: an embedded iframe (video, map)
loads in place; a user-initiated link navigation is intercepted, handed to
RenderActions.openUrl and reports a CLICK; a script-initiated redirect of
the item itself is blocked and reports nothing. openUrl sends http/https to a Custom Tab and other app schemes
(mailto:, tel:, your own deep-link scheme) to ACTION_VIEW; file:,
content: and javascript: URLs are dropped with a warning, because those
read the device instead of navigating.
Declarative actions
An item needs no JavaScript of its own to close itself or open a link. The renderer injects a small bootstrap script ahead of the operator 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.data-actiontype="browser"or"deeplink"next to it is accepted and treated identically.
close wins when both attributes sit on the same element. The click is
swallowed, so the WebView itself never navigates. Plain <a href> links keep
the behaviour described above.
<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>The script talks to the SDK by navigating a hidden iframe to the reserved
optima-action:// scheme, which the renderer intercepts and never loads; no
addJavascriptInterface object is exposed to the page. Every signal carries a
random value generated for that render, which a cross-origin frame cannot
read, so content embedded in the item — a third-party iframe — cannot close
it, resize it or open links on its behalf. Scripts in the item's own document
(including any <script src> you add) are trusted like the item itself: only
include scripts you would let act on the item.
A data-link opens only when the user activated the item within the last
1.5 s — a tap, Enter / D-pad centre / Space, or a click from an accessibility
service (TalkBack, Switch Access, Voice Access); a link triggered by a timer or
script is ignored and logged as content link blocked (no user activation).
Auto-height
The WebView is sized to its content. It starts 1dp tall and invisible; the
bootstrap measures body's box plus its vertical margins (not
documentElement.scrollHeight, which never drops below the viewport) and the
view takes that height before it is shown. A ResizeObserver on body (with
load/resize events as the fallback) keeps it in step as images and fonts
load. CSS px equal dp in the WebView's default viewport, so no density
conversion is involved. The impression dwell timer starts only once the item
is visible at its real size.
An item without a <!DOCTYPE> gets <!DOCTYPE html> prepended: in quirks
mode body is stretched to the viewport, which would make the measured height
follow the view instead of the content. Author the item as you would for the
Web SDK, where it renders in the host page's standards mode anyway.
Set display.htmlMode = HtmlMode.OFF to disable this renderer entirely. An
unstructured item then never becomes a Presentation: it is emitted as a
ContentItem(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 (display rules, _optima_seen) — same as an
unregistered structured type — so it is on your own code to avoid
re-showing it if that matters for your UI.
HTML in-app messages
An Optima Campaign mobile_inapp template authored in HTML (rather than
the built-in title/body/image/CTA form) reaches the SDK as an ordinary
campaign content item with format == "unstructured" — everything in
Unstructured HTML above applies, plus a native frame
OptimaHost draws around it.
Overlay vs inline follows the item's display.placement exactly as for
any other item (Slots and placement): an overlay
message needs nothing beyond the app-root OptimaHost() every app already
has; an inline message needs an OptimaSlot("<slot>") matching the
template's configured slot name, the same as a structured inline item.
The three frames
OptimaHost picks a frame from display.style/display.position
(overlayFrame(rule), com.optima.sdk.content) and draws it around the
item's WebView — the HTML itself stays transparent and draws the visible
card; the frame only positions it:
style | Geometry |
|---|---|
card (default) | 16dp inset on all sides, 16dp corner radius, max width 420dp, at position top / center / bottom (default bottom). |
bar | Edge to edge, no radius, pinned to top or bottom only — center falls back to bottom. |
modal | Always centred over a 40%-opacity black backdrop, max width 420dp; tapping the backdrop dismisses the item when it's dismissible. |
An unrecognised style value is treated as card. This is independent of
InAppRenderer's own style handling for structured mobile_inapp
items (display rules) — that renderer draws its own
AlertDialog/Surface chrome; the frame described here only applies to
format == "unstructured" items.
The native close button
A dismissible item whose HTML contains no data-actiontype="close"
element of its own gets a small native ✕ drawn in the frame's top-right
corner (needsNativeClose, a simple case-insensitive check for that
attribute in the item's HTML). Every close path — the native ✕, a backdrop
tap on a modal, or the HTML's own data-actiontype="close" element —
reports the same dismiss action. Recommendation: include your own
data-actiontype="close" element styled to match the message (see
Declarative actions) so you control its look and
position instead of getting the generic native one, and set html, body { background: transparent; } in the item's CSS so only your card's own
background paints — the frame itself draws nothing but position.
display.htmlMode = HtmlMode.OFF applies here exactly as it does for any
other unstructured item: the message never becomes a Presentation (so it
never gets a frame either) and is instead emitted as a ContentItem event.
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 Android; dropped"). They are excluded from ContentLoaded's count. If
you're targeting the same slot from both web and mobile, expect
web_personalization items to simply never reach an Android device — there
is nothing to configure to change this, and nothing about the SDK is broken
if you never see one come through.