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 Message button.

Keep the Audience set to "Show to all users". As you will soon see, in-app messages with the "Push Permission Prompt" action will only display to unsubscribed push subscriptions.

Message design

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. See Design In-App Messages with Drag and Drop for details.

Push permission prompt click action

Button and image blocks have a Push Permission Prompt click action which means when this button/image is clicked, our SDK will automatically trigger the operating system's required push permission prompt.

Any users that have previously denied push permissions when shown the required prompt, this button will instead show an alert asking the user if they want push and direct them to the app's notification settings to enable.

📘

Displayed to unsubscribed subscriptions only

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

Triggers

The audience we set previously are the users eligible to receive the in-app message. The triggers determine when the message will show.

We provide 4 trigger options: 3 of which do not require any code and a 4th option that gives you more control to programmatically trigger the prompt.

Depending on your app, you may want to show the prompt immediately when the user opens the app (select On app open), but in most cases, you will likely want to give your user time to use and enjoy your app first before asking them to commit to receiving messages.

You can add the Session Duration trigger and set a time to wait before the message shows. In this example, we will set this to greater than 300 seconds (5 minutes).

📘

Testing?

Set the trigger to On app open or Session Duration greater than a few seconds while testing to make sure it looks the way you want. You can always come back to update this later.

Schedule and re-trigger

Finally, you can schedule the message to start showing and determine the frequency at which it will appear.

The default is to show only once. This won't get us many push subscribers because they will only see this message once and never again.

If you select Every time trigger conditions are satisfied that will be very aggressive and will constantly show to users potentially creating a bad user experience.

The recommended option is to show the message Multiple times. This allows you to set the maximum number of times the message will show and place a gap in between each message's occurrence.

In this example, we set the first value to be a very large number (9999) and a gap of 2 weeks. This means the message will show one time every 2 weeks for a total of 9999 times.

We want the first number to be a very large amount because we always want to prompt unsubscribed users to subscribe but we don't want to annoy them so we only ask every 2 weeks. You can change the cadence from 2 weeks to more or less depending on the use case.

👍

Push prompt with in-app message setup complete!

Update your message and set it live. You can now monitor your stats and update the gap in between days as needed.

Programmatically show the required permission prompt

Developers: you can trigger the required permission prompt anytime using the our requestPermission() or optIn() methods. It is recommended to use these at strategic times like through a Preference Center or your own custom setup.