Sending In-App Messages

In-App Messages are highly customizable pop-up modals that Mobile App user can receive when they are inside your App. This guide will go over how to set them up and all features available.

Starting In-App Messages

Navigate to Messages > In-App to create, view, edit, pause/resume, duplicate, and delete your In-App Messages.

Templates

OneSignal has five out-of-the-box In-App templates for you to quickly get started. These templates are professionally designed with rich-media content to help you deliver a quality experience to your app users. These include: Welcome Message, Push Permission Prompt, Promotions, New Feature Announcements, and App Store Rating request.

You can customize these templates with your own branding and set them to an active state in a few minutes.

Create New In-App

Add a Message Name that describes the purpose of the message and will help easily find this later as you create more!

Step 1 - Audience

Select the audience eligible to receive your message. You can include and exclude segments of users if you've set up Segments.

🚧

IMPORTANT: Segments Include Unsubscribed Devices

Segments for In-App Messages include both Subscribed & Unsubscribed mobile devices.

Example: Rate My App

Let's use the default App Store Rating Template to ask all users with over 3 sessions to rate your app. First setup a segment using Session Count > 3. Optional: You can setup a second segment to exclude users that already rated the app. You can track users that were asked to rate already using Data Tags within the the In-App Message.

Step 2 - Design Your In-App Message

This is where you create setup how the message looks and functions when clicked.

Message Type

This is where the In-App Message will be located and how it appears on the screen.

In-App Messages work in Portrait and Landscape mode. To test in both modes, you will need to send it to yourself. See Test Sending The Message below once you have finished setting up your IAM.

Cards - Carousel

You can add up to 10 cards or screens for a Carousel effect. Each card can have any combination of customizable Blocks. Cards are only supported in the Full Message Type and require a Paid Plan.

Add Card to add more cards and swipe the IAM Demo screen to view the card like a real device!

Remove Card # can be found at the bottom of the cart to remove that card.

Blocks

Click Add Block to create a Button, Image, or Text elements.

You can drag, clone, delete, show/hide advanced settings of blocks using the Options at the top right of each block.

Tag substitution for In-App personalization is supported on the following fields:

• Text Block - Content
• Image and Background Image Block - URL to upload the image and Click Action URL
• Button Block - Content and Click Action URL

You can check the In-App tag substitution example here.
Note: Tag Substitution will be supported only on iOS version 3.3.0+ and Android version 4.3.0+ SDKs.

Text Block

Text blocks provide Color, Size and Alignment options.
Not Currently Available: font, italicized, and bold options.
If you want to setup different languages, you will need to setup different IAM with text blocks in the languages you desire. Use Segments to setup Audience by Language.

You can use data tags for the text blocks to personalize your content. Reference example here.

Image Block

Click the Upload button or add a direct url to the image (make sure it includes the file extension like .png, .gif, .jpg).

Image Blocks can contain Click Actions or can dismiss the IAM if you select the Options > Show Advanced Settings > Dismiss on click.

You can display different images and background images to your users using tag substitution on the Image upload URL. You can also use tag substitution on the Image Click Action URL and direct your users to different links. Reference example here.

Button Block

Button blocks provide Button Text, Background Color, Text Color, Size and Alignment options.
Not Currently Available: font, italicized, and bold options.
If you want to setup different languages, you will need to setup different IAM with blocks in the languages you desire. Use Segments to setup Audience by Language.

Clicked buttons will remove the IAM by default. If you don't want the button to dismiss the IAM (for example adding multiple Tags or Outcomes), you must uncheck the Dismiss on click option. You can hide/show this within the Options button in top right of the block > Show/Hide Advanced Settings.

Buttons can do more than dismissing the IAM with Add Click Action like:

• Tag users
• Send Outcomes
• Prompt for Push or Location
• Deep-Link to a page of the app

You can use data tags to personalize the button text and the click action URL. Reference example here.

Add Click Action

Click Actions can be added to Button and Image Blocks.

See How to Deep Link From An IAM for more details.

Example: Rate My App Actions

Let's send the user to the app store when they click the Image or Rate Now button. Using the URL Click Action you can add your App's Store URL. See Deep Link to Market if you need more details on this.

If you want to set for iOS and Android App stores separately, you can easily duplicate this IAM and target 2 Segments, one for Android and another for iOS using the "Device Type" data filter. Simply update this URL for the Android and iOS Segment targeted in each URL Action.

If the user clicks the button to dismiss, you can add a Data Tag to mark that the user selected "Remind Me Later" and we can re-target them again at a later time with this same message or send them a push!

Test Sending the Message

You can test In-App Messages on your Test Devices by clicking "Send to Test Device" button at top right of the Messages step.

This will send a push notification that you click to open the app and view the In-App Message test.

🚧

Push Notifications for IAM is only for Testing

For Testing Purposes: Your device must be subscribed to get the Test In-App Message. The test will not work if your device is unsubscribed.

Regular IAM will work on unsubscribed devices, but for Testing, you must be subscribed.

You will not see a push notification when setting the In-App Messages live.

Step 3 - Triggers

The trigger is a custom option for when to show this message. You can trigger the IAM when the user opens the app or setup a custom triggers programmatically with addTrigger method.
Triggers can be combined with AND and OR operators to only show under very specific conditions.

📘

Advanced Triggering

More details on how triggers work below in the FAQ.

Step 4 - Schedule

Start Showing is when the message will begin to be presented to users. If the specific time set has not been reached, the message cannot be triggered.

Stop Showing is the time after which the message cannot be triggered any longer. You can also Show forever which means it will show until you Pause it or delete the App.

Schedule Advanced

By default In-App Messages must be dismissed by a user action:

• Clicking the x button in the corner
• Clicking one of the elements with "Dismiss on click" selected
• Swiping the message away

Select Dismiss after a certain amount of time to dismiss the IAM automatically after X amount of seconds.

How often do you want to show this message?

Every time trigger conditions are satisfied will show this message each time the Trigger events are met.

Multiple times allows you to set a specific amount of times this message can be shown within a set timeframe.

For example, if you set: "2 times with a gap of 1 hours in between" - The message will be allowed to trigger a total of 2 times. The first time when the triggers are met, then the 2nd time when the triggers are met and 1 hour has passed.

If you set "12 times with a gap of 30 days in between" - The message will show roughly once a month for a year.

🚧

Triggers Must Be Satisfied

If the Trigger is On app open or Session Duration then the user must open the app to see it again.

If trigger is Duration since last in-app then the message will show after this is satisfied if longer than the repeat timeframe.

If the trigger is a programmatic In-app trigger, then the method must be called again after the timeframe.

---

FAQ

How do triggers work?

In-App Message triggers are handled by our SDK using the addTrigger or addTriggers method. A trigger is a key: value pair of string or integer data that you set programmatically in your app when an event occurs.

For example, if you want to send an IAM when a user reaches level 5 and level 10 of your game. Each time the use grows a level, you would call for example OneSignal.addTrigger("level", 1); then when they reach level 2, you simply update the trigger OneSignal.addTrigger("level", 2); and so on. At OneSignal.addTrigger("level", 5); you can then have the IAM show to the user by setting the key as level is 5 or level is greater than or equal to 5

Then continue to update the level up to level 10 or higher if you want to continue this flow.

🚧

Triggers are not tags.

The value of the trigger is not viewable within the OneSignal dashboard, but you can view the current trigger value programmatically with the getTriggerValueForKey method on the OneSignal SDK.

How can I target my unsubscribed users?

Unlike push notifications, in-app messages will be sent to subscribed and unsubscribed users. If you want to target only unsubscribed users:

1. Select the segment of devices you want to target.
2. Set the in-app message to only send with a trigger.
3. Within the app set the in-app trigger to fire only if the user is unsubscribed. You can use the getPermissionSubscriptionState method to check the subscription status of the device.

Can the in-app message look like the basic device system dialogue?

While in-app messages do not utilize the device’s basic system dialogue, it can be customized to be shown in the center middle of the device like the system dialogue and show just a plan background and text.

Will OneSignal support localization on the in-app messages?

Not for v1 in the same way as supported currently with push, but we plan to add this. Currently, you can set up different in-app messages for different languages and target a Segment based on the language our SDK automatically detects.

Is the WYSIWYG preview accurate?

The WYSIWYG preview is very close to what your users will actually see. However, devices have a range of screen dimensions and so we have an easy-to-use preview on device option that will send the in-app message to any test device you'd like immediately to take a look at it on your own phone.

Can I upload my own HTML template?

Currently no. If this is a feature you would like, please contact support with your use case and details of how you would like to use it.

Is tag substitution available?

Yes, you can use data tags to personalize the content and click action behavior of your users. Here is the list of In-App Message fields that support tag substitution.

Can I send in-app messages via the API?

Currently no. If this is a feature you would like, please contact support with your use case and details of how you would like to use it.

What are the dimension limits for background image?

We show IAMs based on the dimensions of the phone currently being displayed on. There are a few common aspect ratios for devices and resolutions (especially for Android) which could all affect the viewing of the IAM.

A 16:9 aspect ratio is the most common for devices, but 4:3 and 3:2 aspect ratios are close compromises.

How to deep link within the app from an IAM?

If you just want to open a URL when clicking the IAM, add the URL to the button or image "URL" field. An in-app browser will appear with the url.

If you want to deep link into another page of the app, using the Click Action you can specify an "Action Name". This action name is available within the In-App Message Click Handler method inside the OSInAppMessageAction object called clickName.

When you detect this clickName you can then deep link to the page in your app.

Example: If you normally detect on a push notification the data "deepLink": "page3" using the Notification Opened Handler, then in the In-App Message Click Handler method you would specify page3 for the clickName.

You can have different clickName's for the image, button and background. If you don't sent a clickName, then it will be "null" and you can ignore it.