Both Apple's Human Interface Guidelines and Google's developer documentation highly recommend providing context for the type of information that will be sent and its value, when asking for push notification permission, and offering users a clear way to opt-out.

iOS allows their native push prompt to be shown one time. It cannot be re-shown if dismissed or if previously allowed. If it was shown in the past, the user must be sent to their phone settings to enable notifications.

Android allows its native push prompt to be shown up to two times if the user selects "Don't Allow". Prompting only happens for Android 13 or newer devices. If "Don't Allow" was selected in the past, the user must be sent to their phone settings to enable notifications. Older subscribers are opted-in by default.

Regardless, using OneSignal's In-App Messages, you can easily create and customize a "soft-prompt" to ask users to grant your app permission to send push notifications. If the user selects “Allow”, the system’s push permission prompt appears. Otherwise, the in-app message will be closed. However, prompting too often can result in a bad user experience for your users.

Preparing for Setup

Before getting set up, check that you do not show the native prompt:

• if present, remove the push prompting methods.
• if present, remove any other reference to iOS native API requestAuthorizationWithOptions.
• if present, remove any other reference to Android native API requestPermissions with android.permission.POST_NOTIFICATIONS

Also, make sure you have the latest version of the OneSignal SDK in your app.

Set Up The In-App Message

In Messages > In-App edit the default Push Permission Prompt template or create your own with the New In-App button.

Keep the Audience set to "Show to all users". You can select Show to Particular Segment(s) if you want to only prompt under certain conditions using Segments.

📘

In-App Messages will display to Subscribed & Unsubscribed Devices.

However, by default, In-App Messages that have a "Push Permission Prompt" action will not be shown to subscribed devices.

Set Up Your Message

In-App Messages can be customized to your app's theme and how you like to communicate. Use any wording to ask your users to subscribe and gauge their interest. For more details see Design Your In-App Message.

Add Push Permission Prompt Action

📘

Displaying to Unsubscribed Devices

In-App Messages that have a "Push Permission Prompt" action will not be shown to users who have already allowed notifications.

If not using the default template, create a button and/or image block(s), then select Add Click Action > Push Permission Prompt. When this button is clicked, OneSignal will automatically trigger the native Push Permission Prompt.

If users have previously denied push permission when shown the native prompt, this button will open the device settings for your app.

To target Android 13+ users, ensure you are using a version of the OneSignal SDK released after July 2022. Follow the Android 13 Push Notification Developer Update Guide.

See the In-app Message Click Actions guide for more details on adding a Push Permission Prompt, Location Permission Prompt, and more.

Triggers

Select the On app open or set the Session Duration trigger to a time of your choosing to determine when users will see the in-app message.

Triggering Programmatically

If your app is triggering the Push Prompt Action in-app message using the SDK addTrigger method, you will want to verify the device is subscribed first using the SDK getDeviceState method. Here is an example of how that works.

//Example
OSDeviceState device = OneSignal.getDeviceState(); 
boolean areNotificationsEnabled = device.areNotificationsEnabled();
if !areNotificationsEnabled {
  OneSignal.addTrigger("showPrompt", "true")
}

Schedule and Re-Trigger

Finally, you can schedule the message to start showing.

If you want to be aggressive with your prompting, select "Every time trigger conditions are satisfied" which will show the prompt almost every time the unsubscribed users opens the app, based on the triggers set.

Recommended: If you want to show the prompt with less frequency, use Multiple times with 9999 and a gap of 3 days in between. The first number is how many times you want the message to show and the 2nd number is the timeframe in which to wait before showing the message again.

In this case, if the user is unsubscribed, they will be prompted every 3 days for a total of 9,999 times until they subscribe.

This can always be changed later based on how often you want to prompt for push.

Programmatically Triggering the Native Permission Prompt

Not Recommended: use the OneSignal Push Prompt methods to trigger the Permission Prompt. It is recommended to use the above or your own soft-prompt first before triggering this method.