This guide is for mobile app push subscribers. For web push, see Web Permission Prompts.

Your users must opt-in aka "subscribe" to receive push notifications from your mobile app. This requires a specific system-level permission prompt to be shown and interacted with. You can trigger this prompt to display anytime using the requestPermission() method. However, iOS only allows this to be shown 1 time and Android 2 times. After which, the user must be sent to their phone setting to enable notifications.

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.

Using in-app messages, you can easily create and customize a "soft-prompt" to ask users to grant your app permission. If the user selects “Allow” on your in-app message, 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. This guide gives a general example how to set this up properly.

In-App Push Prompt Setup

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

• if present, remove our SDK's requestPermission() or optIn() 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.

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 14 days in between. The first number is how many total 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 14 days for a total of 9,999 times until they subscribe. Subscribed devices will not be re-prompted unless they unsubscribe again.

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

👍

Push Prompt with In-App Message Setup Complete!

You can now monitor your stats and update the gap in between days as needed.

Programmatically Triggering the Native Permission Prompt

Not Recommended: use the OneSignal requestPermission() or optIn() methods to trigger the Permission Prompt. It is recommended to use these at strategic times like through a Preference Center or your own custom setup.