In-app experiences

Engage in-app experiences are not OS notifications. The SDK downloads versioned content over HTTPS, caches it, evaluates eligibility and triggers locally, and renders DivKit inside the app.

There is no SSE or WebSocket connection. Foreground refreshes and remote invalidation signals keep the cache current; cached schedules remain usable during intermittent connectivity.

Overlay experiences

Overlay formats are banner, modal, and fullscreen. The application can pause all overlays during sensitive flows or decide per candidate.

Engage.inApp.overlays.displayDelegate = InAppOverlayDisplayDelegate { candidate ->
    if (isCheckoutCriticalStepVisible()) DisplayDecision.DEFER
    else DisplayDecision.ALLOW
}
 
Engage.inApp.overlays.pause()
Engage.inApp.overlays.resume()

Engage.inApp.overlays.displayDelegate = (candidate) {
  return isPaymentVisible ? DisplayDecision.defer : DisplayDecision.allow;
};
 
await Engage.inApp.overlays.pause();
await Engage.inApp.overlays.resume();

Engage.inApp.overlays.displayDelegate = { content in
    isPaymentVisible ? .deferDisplay : .allow
}
 
Engage.inApp.overlays.pause()
Engage.inApp.overlays.resume()

Deferring preserves the candidate for a later safe opportunity. Discard only when the experience should never display for that candidate.

Embedded placements

The placement key connects an authored experience to a stable slot in application UI.

EngageInAppPlacement(
    key = "home.hero",
    modifier = Modifier.fillMaxWidth(),
)

const EngageInAppPlacement(
  placementKey: 'home.hero',
  height: 180,
)

import EngageInApp
 
EngageInAppPlacement("home.hero")

Flutter must provide an explicit height because the native renderer is hosted in a Platform View. The placement collapses when nothing is eligible unless authored presentation reserves space or the host supplies a placeholder.

Headless placement

Use the headless stream only when the application intentionally owns rendering:

lifecycleScope.launch {
    Engage.inApp.placement("home.hero")
        .collectLatest(::renderCustomExperience)
}

Engage.inApp.placement('home.hero').listen(renderCustomExperience);

for await content in Engage.inApp.placement("home.hero").updates {
    renderCustomExperience(content)
}

The standard placement is preferred because it shares the native DivKit runtime, action router, impression lifecycle, and rendering behavior with overlays.

Custom actions

Server-authored content can invoke an application-owned action. Register handlers early and validate arguments.

val registration = Engage.actions.register("open_order") { action ->
    navigator.openOrder(action.arguments.requireString("order_id"))
    ActionResult.COMPLETED
}
 
registration.close()

final registration = Engage.actions.register('open_order', (action) async {
  navigator.openOrder(action.arguments.requireString('order_id'));
  return ActionResult.completed;
});
 
await registration.cancel();

let registration = Engage.actions.register("open_order") { action in
    navigator.openOrder(action.arguments.requireString("order_id"))
    return .completed
}
 
registration.cancel()

Actions from push, in-app, and Message Center use the same registry.

What the console controls

The published experience defines target apps, audience, triggers, schedule, locale variants, allocation, priority, conflict policy, frequency and cooldown, presentation, conversion goal, and personalization sample context. See Author in-app experiences.