OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Sending In-App Messages

OneSignal features - Sending In-App Messages with the OneSignal Messaging composer

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.

Quick Reference

Details

Getting Started

Where to go to get started

Designing Your Message

Setup different IAM elements:

Set Triggers

You decide on when this message should show to users.

Schedule

Time when the message should start and stop showing to users. Also includes:

Analytics

Once your IAM are setup, monitor their performance based on how many times they have shown (impressions) and which blocks were clicked.

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.

Message Type

Description

Top

Drops down from the top of the screen.

Center

Expands out from the center to partially fill screen.

Bottom

Pops up from the bottom of the screen.

Full

Expands out from the center to mostly fill screen.

Carousel

Add up to 10 screens (cards) with their own customizable content. Must have a Paid Plan and select the Full Message Type for this feature.

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.

In-App Messages work in Portrait and Landscape mode.

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.

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.

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.

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

Add Click Action

Click Actions can be added to Button and Image Blocks.

Click Action

Description

URL

Opens an in-app browser to the URL you specify.

Push Permission Prompt (iOS)

Prompts iOS devices to subscribe to push if they click the button.

Location Permission Prompt

Prompts iOS and Android devices to opt-in for Location-Triggered Notifications.

Send Outcome

Adding an Outcomes will track block clicks for analytics purposes.

Tag User

Adding Data Tags is useful for Segmentation and further actionable message targeting.

Custom Action ID

Used for detecting the block clicked within the SDK In-App Message Click Handler method.

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.

Trigger

Description

On app open

Show message upon next app open.

Use this to make sure all users within the segment get the message when they open the app.

In-App Trigger

Show message when user performs certain action.

Message shows when calling the In-App addTrigger methods for the corresponding key value pair.

Session Duration

Show message after x seconds within the current app session.

Duration Since Last In-App

Show message after x seconds since the most recent in-app message.

๐Ÿ“˜

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 setup 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 a feature you would like, please contact support with your use case and details of how you would like to use.

Is tag substitution available?

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

Can I send in-app messages via the API?

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

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.

Updated about a month ago



Sending In-App Messages


OneSignal features - Sending In-App Messages with the OneSignal Messaging composer

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.