Skip to content
Optima docs
SDKsAndroid SDK

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 one OptimaHost() near your app's root to catch overlay-placement content (dialogs, bottom cards) from every slot, plus the implicit __overlay slot used by items with no explicit inline placement.
  • Headless: call optima.content.slot("homepage_hero") yourself, and render the returned StateFlow<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:

FieldValuesBehaviour
trigger.onload | delay | eventload: 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.
frequencyalways | 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.
dismissibletrue | false | absentWhether 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_daysintegerAfter 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.
placementinline | overlay | absentSee Slots and placement above; absent defaults to overlay.
position / styletop/bottom; card/bar/modalCosmetic — 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's reportImpression modifier) measure this for you on every built-in renderer; if you're rendering headlessly, you own this timing check yourself before calling content.report(item, ContentAction.IMPRESSION).
  • Click: content.report(item, ContentAction.CLICK), fired by the built-in renderers' CTA button. If the item's campaign display carries stop_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 its ttl_days suppression 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: a DISMISS is reported for campaign (token-bearing) items, the dismiss memory (ttl_days rule) 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 a CLICK and opens the URL through RenderActions.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:

styleGeometry
card (default)16dp inset on all sides, 16dp corner radius, max width 420dp, at position top / center / bottom (default bottom).
barEdge to edge, no radius, pinned to top or bottom only — center falls back to bottom.
modalAlways 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.

On this page