Scenarios & Recommended Configs (Android)

The same feature supports several product patterns. Pick the one that matches your intent and copy its config. All snippets assume the SDK is already set up as in Integration.

I want to…	autoFetchOnForeground	Extra code	Campaign condition.target
Show general campaigns as the user browses	true	none	empty (untargeted)
Show a campaign only on a specific screen	see below	refreshEngageInAppMessages(context, target) per screen	set to the screen name
Not show anything on login / splash	false	manual fetch after login	any
Trigger at a custom moment (event, button)	false	manual fetch at that point	any

---

Show campaigns as the user browses (default)

The out-of-the-box behavior. The SDK fetches on foreground and on every screen change (15s debounced). Untargeted (Everyone / Audience, no condition.target) campaigns appear wherever the user is.

engageInAppConfig = PaylisherEngageInAppConfig(fetchEndpoint = "…").apply {
    autoFetchOnForeground = true
}

Good for broad announcements, promotions, and "what's new" messages that are not tied to a screen.

---

Screen targeting

Show a campaign only when the user is on a particular screen (e.g. a wallet promo only on the Wallet screen).

How it works: the SDK passes the current screen as target in the fetch; Engage returns a campaign only if its condition.target matches (campaigns with no target match any screen). You drive this by calling refreshEngageInAppMessages(context, target) when a screen becomes visible, using a stable screen name that matches what you set on the campaign.

// Call when the screen/route becomes visible
PaylisherAndroid.refreshEngageInAppMessages(context, target = "wallet")

In Jetpack Compose, react to the selected route so every screen reports its name once:

LaunchedEffect(selectedTab) {
    PaylisherAndroid.refreshEngageInAppMessages(context, target = selectedTab.name.lowercase())
}

Then, in the dashboard, set the campaign's screen target to wallet (see Campaign Setup). Use the same string on both sides, and keep the names stable and consistent with iOS.

---

Don't show on login / splash

You rarely want a promo to interrupt the login or splash flow.

• Multi-Activity apps: add the Activity's class-name fragment to excludedActivities (the default already excludes "Splash"). Messages fetched on an excluded screen are queued and shown on the next eligible screen.

  excludedActivities = listOf("Splash", "Login")

• Single-Activity / Compose apps: class-name matching can't distinguish screens. Set autoFetchOnForeground = false and fetch after the user reaches an eligible screen (e.g. after login, on the home route):

  PaylisherAndroid.refreshEngageInAppMessages(context, target = "home")

---

Trigger at a custom moment

Set autoFetchOnForeground = false and call the manual fetch exactly when it makes sense — after an event, a purchase, or a button tap.

PaylisherAndroid.refreshEngageInAppMessages(context)               // no screen target
PaylisherAndroid.refreshEngageInAppMessages(context, "checkout")

The manual call is not gated by autoFetchOnForeground, so it always fires when you invoke it.

---

How many messages at once

maxMessages (1–5, default 1) caps how many messages a single fetch may return. Keep it at 1 unless you deliberately want to surface several queued messages in one session.