In-app messages quick start guide
All you need to know before starting to send in-app messages
In-app messages are delivered to your app users when an event is triggered while the app is open. Opt-in is not required for this type of message.
In-app campaigns can only be configured as a response to real-time events from your app (firing an event from the API cannot trigger an in-app campaign).
Prerequisites: SDK integration
In-app messages require you to configure your app in your Xtremepush project and that you complete the integration of the Xtremepush SDK. See details on how to do this for Android and iOS.
If your app is not fully native but built with a mobile framework you will need the iOS and Android prerequisites outlined above, but your code changes will relate to the specific mobile framework you are using. We support a range of popular mobile frameworks including:
Once you have integrated the SDK in your app you will need to turn on In-app messaging by using the following method:
.setEnableInApp(true)
[XPush setInAppMessageEnabled: YES];
XPush.setInAppMessageEnabled(true)
Enable the in-app channel
To be able to use the in-app channel, it must first be enabled by a Project or Company Admin user, from Settings > Apps & sites > click on the matching app by toggling the In-app slider and clicking on Enable. No further configuration is required.
Once you have enabled the in-app channel, you will be able to see In-app / On-site Messages as an available channel from the campaign builder page.
Add real time events to trigger messages
In-app messages are triggered by real-time events. You need at least one real-time event (for example a specific page view) to trigger an in-app message, or one can be triggered on session start.
Once the SDK has been deployed you can add these events easily by calling a simple method in your iOS or Android app. Trigger events are added to your app by using the eventHit method of the Xtremepush SDK.
mPushConnector.hitEvent("EVENT_NAME");
[XPush hitEvent: @"EVENT_NAME"];
XPush.hitEvent("EVENT_NAME")
Custom events may be triggered when sections of the app are opened, buttons are pressed or more complex events occur, such as purchases or the completion of goals. You must select an event that will trigger the message to be sent while the app is open.
For more detail on events, including sending single values or key/value pairs along with events, check out the iOS and Android docs.
Testing...
Running tests is encouraged before start sending in-app campaigns to your customers. You'll find details on how to test below.
Test in-app messages
In-app messages can only be used in standalone campaigns. To create a test campaign go to: Campaigns > Create Campaign > Single-stage and select In-app / On-site message.
You can review more details about how to set up an in-app campaign from this guide and also have a look at our creative guidelines guide for the best results.
To launch a test campaign you can manually fire an event from your app, by using the SDK event method.
mPushConnector.hitEvent("EVENT_NAME");
[XPush hitEvent: @"EVENT_NAME"];
XPush.hitEvent("EVENT_NAME")
An event is created in your project when you fire it for the first time from your website, or you can also manually create it by navigating to Data Manager > Events > Create event.
Once you have fired this event or created it, you will be able to select it by typing the event name into the Events tab (under Custom event). Configure all other options following our guide.
Navigate to the Segment tab to specify recipients of the campaign. If you have more than one app integrated you need to specify which one you want to target, otherwise, the content will appear in all of them. If you have multiple users and you want to target a particular one, you can do so by selecting Create Custom Segment > identifier > user ID equals and providing the user ID you want to target. This will only work if you have previously set your user ID in the Segmentation Engine.
Alternatively, you can target by device ID by selecting identifier > device ID equals.
How to obtain your device ID?
Review our dedicated guide to learn how to obtain your device ID.
Count recipients before launching the campaign
Whenever launching a campaign it is a best practice to use the Calculate recipients feature to count recipients and make sure that your targeted audience for this campaign is what you are expecting.
Once you have launched the campaign, and in order to test it, you will need to go back to your app and fire the event again. The in-app message should appear immediately after you fire the event.
Troubleshooting: Debug logs
You can turn debug logs to review issues. See our dedicated guide for instructions on how to enable debug logs.
Updated about 2 years ago