In-app message
Overview
In-app message is a banner that can be displayed when your app is running. It may have various layout variants, because it is fully customizable by HTML. The campaign is triggered and displayed depending on the configuration settings.
Read more about creating in-app messages here.
In in-app messages, you can use:
- the safe area mode on iOS from the
5.1.0version, - the display cutouts mode on Android from the
6.1.0version.
Requirements
- Recommended Mobile SDK version:
- Android - 5.3.0 or newer
- iOS - 4.12.0 or newer
- React Native - 0.12.0 or newer
- Flutter - 0.5.0 or newer
- If your in-app content (such as JavaScript, CSS, images, or fonts) is being loaded from your own server via HTTP and you have configured CORS policies, you need to set the contentBaseUrl to your server’s address. For example, if you’re loading resources from
https://www.synerise.com/example/font.woff, you should configure contentBaseUrl tohttps://www.synerise.com(check this option in the Settings). - Enable the
IN_APP_DEFINITIONS_COMMUNICATION_READ(Experience Hub) permission in the Profile (formerly Client) API key used by the mobile application so the mobile application can fetch in-app messages.
The API key permission matrix with the in-app permission
Good practices
Campaign planning recommendations
Using a large number of in-app messages in your application can impact rendering time, message delivery, and battery usage.
To maintain optimal application performance when using in-app campaigns:
- Avoid assigning more than 10 in-app messages to the same trigger event.
- Avoid having more than 20 in-app messages active at the same time in your application.
- Review and archive in-app campaigns that you no longer need.
Template construction
When creating or editing in-app message content:
- Place the the
SRInApp.close()(orSRInApp.hide()) method at the beginning of the JS script. - Use try/catch to handle possible fatal errors in the JS script.
- Handle situations where Jinjava inserts return empty data.
- When adding external links to your message:
- Only link to sites you trust.
- Don’t link to large images that may negatively affect performance.
- Don’t link to resources whose CSS/HTML may be blocked. If you have resources loaded from your own URLs, set
Synerise.settings.inAppMessaging.contentBaseUrland use relative paths in HTML/CSS.
Configuration
In-app message campaigns are served by the Synerise backend.
Check possible available configuration options in the Settings.
JavaScript methods in in-app messages
See “Using in-app template builder” in the User Guide.
Events generated by in-app messaging
For information about events generated by in-app messaging, see the event reference.
inApp.capping event in the SDK Settings - Enable/disable sending in-app capping event.Setting up a global control group for in-app message
For information about global control groups in in-app messages, see the global control group article.
Handling actions from in-app messages
Handling main actions from campaigns depends on the campaign type and operating system and it is described here.
Controlling behavior and actions
You may control an incoming in-app message and decide whether to show it (the display of in-app message can be triggered by occurrence of specific events). By default, the SDK allows in-app message display.
The user interface allows selecting up to 3 trigger events, however, in Android, only for 5.8.1 SDK version (released on 28.08.2023) or higher all triggers are considered altogether. For older SDK versions in Android, only the last event from the trigger list will be considered.
These limitations don’t apply in iOS.
Also, you can be notified (in the form of events) about the campaign actions in the following cases:
- When the in-app message is presented.
- When the in-app message disappeared.
- When additional context is needed to render the campaign.
- When the customer invoked an action.
You can handle the message using:
- OnInAppListener methods for Android.
- InjectorInAppMessageDelegate methods for iOS.
- InjectorInAppMessageListener methods for React Native.
- InjectorInAppMessageListener methods for Flutter.
See the following code samples:
public static OnInAppListener NULL = new OnInAppListener() {
// This method is called after an in-app message is loaded and Synerise SDK asks for permission to show it.
@Override
public boolean shouldShow(InAppMessageData inAppMessageData) {
return true;
}
// This method is called after an in-app message appears.
@Override
public void onShown(InAppMessageData inAppMessageData) {
//...
}
// This method is called after an in-app message disappears.
@Override
public void onDismissed(InAppMessageData inAppMessageData) {
//...
}
// This method is called when a individual context for an in-app message is needed.
@Override
public HashMap<String, Object> onContextFromAppRequired(InAppMessageData inAppMessageData) {
return new HashMap<>();
}
// This method is called when the SRInApp.openUrl(url) method is used in an in-app message.
@Override
public void onHandledOpenUrl(InAppMessageData inAppMessageData) {
//...
}
// This method is called when the SRInApp.openDeeplink(url) method is used in an in-app message.
@Override
public void onHandledOpenDeepLink(InAppMessageData inAppMessageData) {
//...
}
// This method is called when the
// SRInApp.handleCustomAction(name, params) method is used in an in-app message.
@Override
public void onCustomAction(String identifier, HashMap<String, Object> params, InAppMessageData inAppMessageData) {
//...
}
};
Closing a message
In-app messages can be closed with a JS method included in their content, but you can also use a mobile SDK method. This can be used to close top or bottom bar in-app from somewhere else on the screen.
Using this method generates an inApp.discard event.
See the method reference:
Example
This is an in-app message campaign example with full screen presentation.

