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

In-App Message Examples

Common Examples you can use to help get started with In-App Messages through OneSignal.

Quick Reference

Details

Push prompt

Ask Unsubscribed Devices to Subscribe/Re-subscribe to push. OneSignal provides a default Template for this. Here is how to get the most out of it!

Onboarding Tutorial

Share the great functionality your app provides as an onboarding tutorial or trigger it from a tool tip button!

Create a Survey

Ask your users questions and segment them based on their answers!

Target Specific Android Device OEMs

Some Android device manufacturers will force quit your app when it gets swiped away. This prevents users from getting push. This message will help detect those type of device manufacturers and let your users know how to get push at all times.

Trigger IAM from Push Open

Show an IAM upon opening the app from a push.

Ask Unsubscribed Devices to Resubscribe to Push

This example will explain how to ask unsubscribed users to resubscribe to push. If you want to ask iOS devices to subscribe for the first time (recommended) see iOS Push Opt-In Prompt guide.

Step 1. Select the Audience

For both Android and iOS, you would need to duplicate this template and create 2 segments:
Segment 1: Device Type is Android
Segment 2: Device Type is iOS

Step 2 Unsubscribed Device Trigger

Using the OneSignal SDK getDeviceState() method, you can check if the current user is subscribed or not. Then with the addTrigger method, you can then trigger the in-app message once the user is detected to be unsubscribed.

//OneSignal Android SDK 4.0.0+
OSDeviceState device = OneSignal.getDeviceState();
boolean subscribed = device.isSubscribed();
if (!subscribed) {
  OneSignal.addTrigger("unsubscribed", "true");
}

//OneSignal Android SDK 3.15.6-
OSPermissionSubscriptionState status = OneSignal.getPermissionSubscriptionState();

if (!status.getSubscriptionStatus().getSubscribed()) {
  OneSignal.addTrigger("unsubscribed", "true");
}
//OneSignal iOS SDK 3.0.0+
if let deviceState = OneSignal.getDeviceState() {
    let subscribed = deviceState.isSubscribed
    if subscribed == false {
      OneSignal.addTrigger("unsubscribed", withValue: "true")
    }
}

//OneSignal iOS SDK 2.16.2-
let status: OSPermissionSubscriptionState = OneSignal.getPermissionSubscriptionState()
let isSubscribed = status.subscriptionStatus.subscribed
print("isSubscribed = \(isSubscribed)")
if isSubscribed == false {
    OneSignal.addTrigger("unsubscribed", withValue: "true")
}

Set the trigger to be the unsubscribed is true.

Step 3 Create the message with custom action

OneSignal provides a default Push Permission Prompt template which you can customize or create your own.

iOS Click Action for your iOS segment, there is a button Click Action: Push Permission Prompt (iOS). This will show the native iOS prompt if not shown before or it will present an alert to take the user to the App Settings to enable push.

Android Click Action for your Android segment, you can add a Custom Action ID. This will be available within the InAppMessageClickHandler method when the user clicks the button.

The action button example here is prompt_user

Based on the handler name, you can then send the user to the App Settings to resubscribe.
This is handled automatically with the iOS Push Permission Prompt Action, but code available if you want to handle it programmatically.

class ExampleInAppMessageClickHandler implements OneSignal.InAppMessageClickHandler {
  // Example of an action id you could setup on the dashboard when creating the In App Message
  private static final String ACTION_ID_MY_CUSTOM_ID = "prompt_user";

  @Override
  public void inAppMessageClicked(OSInAppMessageAction result) {
     if (ACTION_ID_MY_CUSTOM_ID.equals(result.clickName)) {
        Log.i("OneSignalExample", "Custom Action took place! Starting YourActivity!");
        //example from https://stackoverflow.com/questions/32366649/any-way-to-link-to-the-android-notification-settings-for-my-app
        intent.setAction("android.settings.APP_NOTIFICATION_SETTINGS");

        //for Android 5-7
        intent.putExtra("app_package", getPackageName());
        intent.putExtra("app_uid", getApplicationInfo().uid);

        // for Android 8 and above
        intent.putExtra("android.provider.extra.APP_PACKAGE", getPackageName());

        startActivity(intent);
     }
  }
}
let handler: OSHandleInAppMessageActionClickBlock = { action in
    var message: String? = nil
    if let clickName = action?.clickName, let clickUrl = action?.clickUrl, let firstClick = action?.firstClick, let closesMessage = action?.closesMessage {
        message = String(format: "Click Action Occurred: clickName:%@ clickUrl:%@ firstClick:%i closesMessage:%i", clickName, clickUrl as CVarArg, firstClick, closesMessage)
        print(message ?? "no message")
    }
    // NOT REQUIRED IF USING iOS Push Permission Prompt Action
    if clickName === "prompt_user" {
      OneSignal.presentAppSettings()
    }
}

OneSignal.setInAppMessageClickHandler(handler)

Schedule the message to start showing immediately and confirm.


Create a Tutorial

Let's introduce new users to our app or share a new feature update!

Step 1. Select the Tutorial Audience

For new users, we can setup a segment of First Session less than 1 hour so we can target new users as soon as they open the app. If you have a sign up flow, you can use triggers to start the demo after the user signs in.

If this is a new feature, we can setup a segment for users with session count greater than 2 and Last Session less than 1 hour ago. This way we don't show the sequence for new users that might not be ready for the new feature.

Step 2. Walkthrough Trigger

If there is a sign up flow for your app that we don't want to block, we can setup the in-app trigger to fire as soon as registration is complete.

Another option is to setup the trigger to go off after 3 minutes (180 seconds).

If you are introducing a new feature to users that are already registered, you can also have this sequence trigger "On app open".

Step 3. Create the Walkthrough

Depending on how many screens the walkthrough contains, name the message based on the sequence to find it easier (Tutorial 1, Tutorial 2, etc...).

If available, gif's are highly recommended to animate your tutorial. You can add gif's or images to the image field or use the entire message with the background field.

It is up to you to add a button or not. Generally you would not need to add a button here since clicking the image or background will also set an Action to tigger the next message.

Set the Click Action Name to be representative of the next tutorial to show and dismiss the message on click.

Add the click action to the InAppMessageClickHandler along with the tigger to the next message.

class ExampleInAppMessageClickHandler implements OneSignal.InAppMessageClickHandler {
  // Example of an action id you could setup on the dashboard when creating the In App Message
  private static final String ACTION_ID_MY_CUSTOM_ID = "show_tutorial_2";

  @Override
  public void inAppMessageClicked(OSInAppMessageAction result) {
     if (ACTION_ID_MY_CUSTOM_ID.equals(result.clickName)) {
        Log.i("OneSignalExample", "Custom Action took place! Starting YourActivity!");
        //setup the trigger to the next tutorial window
        OneSignal.addTrigger(ACTION_ID_MY_CUSTOM_ID, 1);
     }
  }
}

Step 4. Tutorial Finish and Repeat

Once you schedule and confirm the message, you will repeat the process for the rest of the tutorial messages using the same audience segments.

Make sure to change the trigger to be the name of the Action ID set in the previous message.
In this example, the second tutorial message will have a trigger show_tutorial_2 is 1.

The second tutorial message will also have an Body Action Name of show_tutorial_3 and so on.

Once you get to the last tutorial page, you can simply dismiss the final message upon body click.


Create A Survey

Using the In-App Message Carousel and Button Click Actions, we can create a survey with up to 10 pages of questions and multiple choice answers. When users provide answers, we can collect the data as Outcomes and/or group them with Data Tags for targeting with messages.

Designing your Survey

  • To get the carousel, select the Full Message Type.
  • Add 3 Text Blocks, 1 Image Block, and 2 button blocks.

Upon duplicating cards for the carousel, all blocks will be duplicated as well to make setting up the survey much easier!

  • Select "+ Create Carousel" to duplicate this card and go back to Card 1.

Our initial setup will look similar to this:

Inside your text and image blocks, you can add any messaging you like and catchy image to get the user's interest.

Users will read the question, select a button and swipe to the next question.

My initial question is going to ask the user if they have time to answer some questions. If they say "Yes" I am going to save that as an Outcome to mark how many people are interested in taking my survey and if they select "No" I will set an outcome that they are not interested at this time. If I get a lot of "No" responses, I might decide to show this prompt at a different time..

  • Select Add Click Action to "Send Outcome"

Adding Outcomes will also add tags, so I can get both - analytics on my survey and create segments for re-targeting with tags.

Here is how the "Yes" button looks, notice that "Dismiss on click" is unchecked. This is found in the top right menu of each block > Show Advanced Settings

The "No" button will work in the exact same way, except we will check the "Dismiss on click" button to remove the In-App Message from view.

More Cards and Questions

Click Card 2 or swipe the carousel to the next page. You will see all the blocks are duplicated.

Here, we can update the text and image but let's keep the question a simply Yes or No. We can do a multiple choice next.

Make sure "Dismiss on click" is not checked on your buttons.

Press the + Add Card button to add the next card and so forth. You can add up to 10 cards.

Final Survey Question

Let's setup a multiple choice question and end the survey.

To get the most space, I'll remove the image and add 2 more buttons. Remember: you can clone blocks to re-use them!

Since this is the end of my survey, I will have whatever button they select dismiss the In-App Message.


Target Certain Android Manufacturers and Devices

Certain Android devices have a known issue where they do not get push notifications when the app is swiped away. More details on this here. This issue affects all push providers, but fortunately OneSignal provides a way to reach out to users of these devices to help educate them on how to enable push for your app if they swipe it away.

Using the Native Android SDK, you can easily check the deviceModel and deviceManufacturer. Then, based on this data, trigger the IAM to ask those users to enable the proper settings on the device for your app.

Some example code looks like this:

//Gets the device model
String deviceModel = android.os.Build.MODEL;
//Gets the device manufacturer
String deviceManufacturer = android.os.Build.MANUFACTURER;
HashSet<String> manufWithIssues = new HashSet<>(Arrays.asList("samsung","huawei","xiaomi","oppo","vivo","lenovo","sony","asus"));
if (manufWithIssues.contains(deviceManufacturer.toLowerCase()){
  //Based on the device manufacturer you can trigger the IAM to show
  OneSignal.addTrigger("device_manuf", "issue_manuf");  //"issue_manuf" == deviceManufacturer
}

In this example, if the current device's manufacturer matches a manufacturer in the HashSet with known issues, it will be passed to the OneSignal addTrigger method which you can use to trigger the IAM setup in your OneSignal Dashboard.

An example message might say:

Your device may not be getting our notifications! 😱

Please check your device settings have our important alerts turned on:

Settings ➝ Device Management ➝ Battery ➝ Unmonitored apps ➝ Add this app πŸ‘

Settings ➝ Apps ➝ this app ➝ App Settings ➝ Notifications ➝ Set as Priority πŸ‘


In-App Message Tag Substitution

In the screenshots below, you can see the In-App configuration with the data tags in the

  • Text block to display the completed level and the reward for that level
  • Image block to display image corresponding to the reward, along with the default image
  • Button 2 text to list down the reward value, along with the default value of 100
  • Background image

And here is how the In-App is displayed on the user’s device based on the completed level.

Trigger IAM from Push Open

Sometimes you may want to trigger a specific IAM upon opening the app based on if a user clicked a related push.

Each push can be sent with additional data which can be detected within the notification opened event. Once the push is clicked and the data is parsed out of the notification, it can be inserted into the addTrigger method to show the IAM.

For instance, if you send the push with additional data: {"iam": "congrats"} and set the In-App Message Trigger to be "iam is congrats". Then your App's Notification Opened Hander can detect the data and pass it into the addTrigger method to display the message.

Updated about a month ago


In-App Message Examples


Common Examples you can use to help get started with In-App Messages through OneSignal.

Suggested Edits are limited on API Reference Pages

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