Overview
An In-App message reaches a user through four stages, from setup in the dashboard to rendering on the device.1
Campaign configuration
The rules you set while creating the campaign: trigger criteria, segment, control groups, priority, and delivery controls.
2
Eligibility and fetch
When the app opens, MoEngage determines which campaigns the user qualifies for, and the SDK fetches and caches them for the session.
3
Trigger and selection
The user performs a trigger action; the SDK matches cached campaigns by trigger and screen, applies delivery controls, and selects one by priority.
4
Display and tracking
The SDK fetches the campaign assets, displays the message on a correctly integrated device, and tracks shown, clicked, and dismissed events.
Campaign Configuration
Trigger Criteria
The trigger criteria determine when a user sees the In-App message. In-App campaigns support four trigger criteria: On session start, On screen load, On custom event, and On push click. For configuration steps, refer to Trigger Criteria.- On session start: Displays the message as soon as a user’s app session begins. A session starts when the user first interacts with the app and ends when the user logs out, enters from a new traffic source, or is inactive beyond the inactivity period (30 minutes by default).
- On screen load: Displays the message on a specific screen or app context. You can target Any screen (the message appears on any screen where a display method is called) or Specific screens (up to five screens, and optionally an app context).
- On custom event: Displays the message when the user performs a custom event tracked by the SDK. You can combine events with AND/OR conditions and add attribute filters to refine who qualifies.
- On push click: Displays the message when the user clicks a linked push notification and opens the app. Use this trigger to continue a push message inside the app, such as opening a detailed offer or landing experience after the push tap. Audience, priority, and delivery controls behave differently for this trigger, as described in the sections below.
- Supported custom events: Only custom events generated and tracked by the MoEngage SDK on the same device can be used as triggers.
- Unsupported actions: Events sent through Data API or any other Server-to-Server (S2S) source, and events MoEngage generates internally such as App/Site Opened, Device Uninstall, Device Reinstall, and User Reinstall, cannot trigger In-App messages.
- Multiple campaigns on the same trigger: The SDK selects and displays only one campaign per trigger, based on priority. In no case can more than one campaign be shown for a single trigger.
Integration Requirements for Trigger Actions
Whether your app needs to call a display method on a screen depends on the trigger. Only On screen load requiresshowInApp() or showNudge() on the target screens; the other three triggers are detected by the SDK without an explicit display call.
Segmentation
While creating an In-App campaign, you can target all users or apply filters to target a specific audience. For configuration steps, refer to Select Target Audience. At the campaign’s scheduled start time, MoEngage evaluates the filter conditions and runs a segmentation query to identify eligible users. MoEngage maintains this user list, so the campaign is ready to deliver when an eligible user next opens the app.
Real-Time and Precomputed Segments
The filters and attributes you select determine how the segment is evaluated. MoEngage displays a banner during campaign creation that indicates which applies.- Real-time segments: Segments built on user attributes, user events, event attributes, and event duration from the last 30 days are evaluated in real time. Users start seeing the message as soon as the campaign is published, and the eligible-user list stays current. Use these for time-sensitive promotions and announcements. For more information, refer to Real-Time Segment Evaluation.
- Precomputed segments: Segments that rely on historical event data beyond 30 days are calculated ahead of time. Membership refreshes on a configurable interval, ranging from 30 minutes to a few hours, so newly qualifying users may not receive the campaign immediately. For more information, refer to Segment Processing.
By default, segment membership is evaluated when the user opens the app, so attribute changes during a session are not reflected until the next app launch. To check eligibility again at the moment of display, enable Re-evaluate Campaign Eligibility.
Re-evaluate Campaign Eligibility
When you enable Re-evaluate campaign eligibility before displaying, the SDK intercepts the trigger and performs a live check against the backend before showing the message. If the user’s attributes have changed during the session (for example, from a Free to a Paid plan), the SDK drops the now-irrelevant campaign, logs a failure, and fetches content relevant to the user’s updated state to show on the next trigger.- SDK version: Android BOM 1.3.0 or later, and iOS 10.10.0 or later.
- Supported segments: Available only for User Attribute–based segments and Real-Time Segment Evaluation (RTSE) segments. The option is hidden for segment types where real-time changes do not apply, such as static segments.
- Limit: Available for up to five campaigns.
Campaign Audience Limit
You can cap how many users a campaign reaches based on engagement metrics such as sends, impressions, and conversions, using total, daily, or instance-level limits. This is useful for controlling reach and cost. For more information, refer to Campaign Audience Limit.In-Session Attributes
In-session attributes group users based on their activity in the current session. MoEngage checks the segmentation criteria first, followed by the in-session attributes.
- Query Parameter: Segments users by query parameters in the URL they arrive on, such as UTM parameters, so you can tailor the message to the source or campaign that brought them in.
- User Type: Segments users as new or returning, based on whether the SDK already has stored details for them.
- Day of the Week: Segments users by the day of the week they visit.
- Time of the Day: Segments users by the one-hour slot of the day they visit.
- GeoLocation: Segments users by country, state/region, and city, or excludes a specific country.
Control Groups
Users in a control group do not see the campaign, which gives you a baseline for measuring campaign impact. Control groups apply to promotional campaigns only; they are not applied to transactional campaigns.- Global control group: A predefined set of users excluded from all marketing campaigns, used to measure the overall impact of your messaging.
- Campaign control group: Users excluded from a specific campaign, used to measure that campaign’s effectiveness.
Campaign Priority
When several campaigns qualify for the same trigger action, MoEngage uses priority to decide which one displays.- Priority level: Set each campaign’s priority to Critical, High, Medium, Normal, or Low. The campaign with the highest priority displays.
- Creation date: If two campaigns share the same priority, the most recently created or published campaign displays.
Campaigns that use the On push click trigger are prioritized automatically, so the linked In-App message displays over other eligible campaigns when the user opens the app after the click. You do not set the priority for these campaigns manually.
Delivery Controls
Delivery controls manage how often and how long In-App messages display, so users are not shown messages repeatedly.
- Limit the maximum number of times a user can see messages from this campaign: Caps the total displays per user to reduce message fatigue.
- Add a minimum delay between two messages of this campaign: Sets the interval between two displays of the same campaign, so the message does not reappear when a user repeats the trigger action in quick succession. This setting is disabled for nudge templates.
- Ignore frequency capping: Lets this campaign bypass the account-level frequency-capping limit.
- Count for frequency capping: Includes this campaign’s displays in the overall frequency-capping count, so you can track the total number of messages delivered to a user.
- Ignore global minimum delay: Lets this campaign bypass the global minimum delay — an account-level setting that enforces a minimum time gap between any two In-App messages, so users are not shown several In-App messages in quick succession.
- Auto dismiss message after: Closes the message automatically after a set duration, even if the user does not act on it.
- Frequency capping and the per-campaign display limit (Limit the maximum number of times a user can see messages from this campaign) are tracked per device, not per user. A user signed in on two devices is counted separately on each.
- The count is stored on the device, so it persists across logout and login on the same device rather than resetting.
Frequency Capping
Frequency capping limits the total number of messages a user sees across campaigns within a defined window, so users are not overwhelmed even when they qualify for many campaigns at once. It is configured at the account level under Settings > Channels > Delivery controls > Frequency capping, where the settings are split into Outbound Channels (Push, SMS, Email, and so on) and Inbound Channels (In-App and On-Site Messaging). For In-App, frequency capping governs how often users see In-App messages in your app across campaigns.- Reset window: The cap resets daily at 00:00, by default in the app’s time zone. You can also reset it based on the user’s time zone.
- Per-campaign overrides: In Step 3 (Schedule and goals) of campaign creation, you can override the account-level cap for a specific In-App campaign using the two toggles below.
- Ignore frequency capping: Lets an important campaign (for example, a service-outage announcement) display even when the user has reached the frequency cap.
- Count for frequency capping: When a campaign ignores the cap, enable this to still have its displays count toward the cap for other campaigns, so you can track the total number of messages delivered to the user.
User Eligibility and Device Configuration
To receive an In-App campaign, a user must:- Belong to the campaign’s target segment.
- Perform the action that matches the campaign’s trigger criteria.
- Use an app build with the required SDK integration in place.
- The SDK is not integrated or initialized correctly for the In-App channel. Follow the integration steps for your platform.
- For On screen load campaigns,
showInApp()orshowNudge()is missing or incorrectly implemented on the target screens. - For On custom event campaigns, the custom event used as the trigger is not tracked through the SDK.
- The user has reached the maximum number of displays for the campaign.
- A campaign-level, global, or frequency-capping delay is still in effect.
- There is a higher-priority campaign available.
- The user is in a control group for the campaign.
- With Re-evaluate Campaign Eligibility enabled, the user no longer matches the segment at the moment of display.
- The user is on a different screen than the one specified in the trigger criteria (screen mismatch).
- Network connectivity is poor, which can delay or fail the campaign asset download (template, HTML, and images).
Campaign Fetch Behavior
The SDK syncs the user’s eligible campaigns from the MoEngage server at specific points, sending the device ID (which MoEngage maps to the user ID), and caches them on the device until the next sync. A fetch happens in the following situations:- First app open after install: On a fresh install, nothing has been synced yet, so the SDK fetches on the first foreground.
- App foreground after the sync interval: Each time the app comes to the foreground, whether a fresh launch or a return from the background, the SDK fetches again only if at least the minimum sync interval has passed since the last successful sync. The default interval is 15 minutes, counted only between two app opens. If the app stays in the foreground for more than 15 minutes, it does not sync again during that session.
- A fresh app process (after the app is killed): If the app is force-closed or terminated and then reopened, the SDK fetches on the next foreground regardless of when it last synced, because the sync state is tracked per app process.
- On user logout: When the current user is cleared and a new user is created, the SDK fetches campaigns for the new user.
- On user login: When a user logs in, the SDK fetches campaigns for the newly identified user.
Campaign Delivery Process
1
App launch
The user opens the app, and the SDK initiates a campaign fetch call to MoEngage, sending the device ID that MoEngage maps to the corresponding user ID.
2
Eligible campaign fetch
MoEngage evaluates which campaigns the user qualifies for based on segmentation and control groups, and returns the list to the SDK.
3
Trigger action detection
The user performs an action that matches a campaign’s trigger criteria, and the SDK detects it.
4
Asset fetch
The SDK makes a real-time call to fetch the campaign’s assets (template, HTML, and images) and personalization data, so the message reflects current content.
5
Message display
The SDK renders the In-App message using the fetched template.
6
Event tracking
The SDK records interactions such as message shown, clicked, and dismissed, and sends them to MoEngage against the user’s profile for reporting.
How MoEngage Selects the Message to Display
When multiple In-App messages qualify for the same trigger action or screen, the SDK narrows them down as follows:- Filtering: The SDK keeps only the campaigns that match the current trigger action and screen name.
- Priority ordering: It sorts the matching campaigns by priority. If several share the same priority, the most recently published campaign ranks higher.
- Delivery control checks (in priority order): Starting from the highest-priority campaign, the SDK applies that campaign’s delivery-control and suppression checks, such as maximum times shown, minimum delay, global delay, and frequency capping. It displays the first campaign that passes all its checks.
Suppression Checks Applied During Selection
Priority only decides the order in which campaigns are considered. Before a selected campaign is displayed, it must also pass every applicable check below. The reason a campaign was not shown is recorded on the campaign’s Info page, grouped into Selection, Delivery, and Display failures. For the full list, refer to Analyze In-App Campaigns.- Higher-priority campaign available: A higher-priority campaign was selected instead.
- Maximum Times Shown: Displaying the message would breach the campaign’s own maximum-times-shown limit.
- Minimum Delay Condition: The campaign’s own minimum delay between two of its messages has not elapsed.
- Global Delay Condition: The global minimum delay between two In-App campaigns has not elapsed since the last In-App message was shown.
- Frequency capping: The In-App frequency cap for the device has been reached.
- Another campaign visible: Another campaign was already displayed at the same time before the selected campaign could have rendered.
- Screen mismatch / context mismatch: The user was on a different screen or app context than the one specified for the campaign.
- Control group: The user falls into the campaign control group or the global control group.
- Campaign state: The campaign is expired, paused, under review, rejected, or archived.
- Render failures: Image or GIF assets fail to load, the required GIF library is missing, the message height exceeds the device, or a file download fails.
SDK Integration
In-App delivery depends on your app being integrated correctly for the channel.- Integration steps: Follow the steps for your platform, including Android, iOS, React Native, and Flutter. For other platforms, refer to the Developer Guide.
- Deep links: In-App messages can send users to a specific screen or URL. Implement deep link handling in your app to support actions that use deep links. For more information, refer to Create Navigation, Deeplinks, and Rich Landing.