In-app messages quick start guide
All you need to know before starting to send in-app messages
In-app messages are delivered to users browsing your app in response to an event trigger. Opt-in is not required for this type of message. Both SDK and server events can be used to trigger in-app message.
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)
Add events to trigger messages
In-app messages are triggered by SDK events, server events or on session start (a system event that needs to be deployed in your app.
SDK events
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")
These 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.
Real-time vs. queued
You can only configure real-time in-app messages by specifying SDK event triggers in standalone In-App / On-site campaigns, which are created from Campaigns > Create a campaign > In-App/On-site. SDK events can also be used in multi-channel In-App campaigns but the message will be retrieved using a polling mechanism.
For more detail on events, including sending single values or key/value pairs along with events, check out the iOS and Android docs.
Server events
Server events can include any backend or external events that can be triggered from integrations or through external API using the hit event method. When using these events, the messages sent to your users will be queued and only delivered after they open your application. For more information review our dedicated guide.
Server events can only be used when you create a standalone In-App / On-site campaign. To create a standalone on-site campaign, navigate to Campaigns > Create a campaign > In-app/On-site.
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.
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 be used as standalone campaigns or as part of single stage campaigns.
To create standalone campaigns go to Campaigns > Create Campaign > In-App / On-site. Creating standalone campaigns allows you to use SDK and backend events as campaign triggers. For more information, see Set Triggers for In-App / On-site Campaigns.
To add In-App messages to multi-channel single stage campaigns, go to Campaigns > Create campaign > Single-stage > Event triggered and then, select the In-App channel in the Setup tab of your campaign.
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 app, 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. 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 18 days ago