Skip to main content

Scenarios & Recommended Configs (iOS)

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…autoFetchOnForegroundExtra codeCampaign condition.target
Show general campaigns as the user browsestruenoneempty (untargeted)
Show a campaign only on a specific screensee belowrefreshEngageInAppMessages(target:) per screenset to the screen name
Not show anything on login / splashfalsemanual fetch after loginany
Trigger at a custom moment (event, button)falsemanual fetch at that pointany

Show campaigns as the user browses (default)​

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

let engageConfig = PaylisherEngageInAppConfig(fetchEndpoint: "…")
engageConfig.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(target:) when a screen appears, using a stable screen name that matches what you set on the campaign.

// Call from each screen's onAppear (SwiftUI) or viewDidAppear (UIKit)
PaylisherSDK.shared.refreshEngageInAppMessages(target: "wallet")

In SwiftUI, centralize it on your tab/navigation change so every screen reports its name once:

// SwiftUI TabView — fire on selection change and initial appear
.onAppear { PaylisherSDK.shared.refreshEngageInAppMessages(target: currentTab.name) }

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 Android.

Don't show on login / splash​

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

  • UIKit apps: add the screen'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.

    engageConfig.excludedActivities = ["Splash", "Login"]

  • SwiftUI apps: class-name matching can't distinguish screens (one host controller). Set autoFetchOnForeground = false and fetch after the user reaches an eligible screen (e.g. after login, on the home screen):

    PaylisherSDK.shared.refreshEngageInAppMessages(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.

PaylisherSDK.shared.refreshEngageInAppMessages()              // no screen target
PaylisherSDK.shared.refreshEngageInAppMessages(target: "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.