Prompt for push permissions

Ask users for push notification permission at the right moment using in-app soft prompts and the native system prompt on iOS and Android.

Overview

A push permission prompt is the operating system dialog shown when asking users whether your app can send notifications. The user’s answer determines whether your app can deliver push notifications that appear as banners, show on the lock screen, and play sounds.

The system permission prompt can only be shown a limited number of times. iOS allows it once; Android allows it twice. If the user declines all attempts, they must manually enable notifications in system settings — a poorly timed prompt can permanently cost you a subscriber!

Both Apple and Google recommend explaining the value of your notifications before requesting permission. Without context, users are more likely to decline — and on iOS, a declined prompt cannot be shown again.

Two ways to trigger the system prompt

You have two options for showing the system permission prompt with the OneSignal SDK. Most apps should start with the in-app message approach.

Option	How it works	When to use
In-app message (recommended)	Configure a OneSignal in-app message — a “soft prompt” — with a Push Permission Prompt click action. If the user taps the button, the system prompt appears. If they dismiss the in-app message, nothing is consumed and you can ask again later.	The default choice. Lets you design, schedule, target, and re-show the prompt without a code release.
Programmatically from your app	Call requestPermission() or optIn() directly from your code. The system prompt appears immediately.	Custom flows where the trigger is owned by your app — preference centers, profile screens, in-app events that warrant a prompt.

Both options end with the same system prompt; they only differ in what the user sees first. You can also combine them — for example, use a soft prompt at onboarding and a programmatic call from a preference center.

On iOS, you can also use provisional notifications, which deliver quietly to the Notification Center without any prompt — ideal for testing or low-friction onboarding.

This guide covers mobile app push. For web push, see Web push permission prompts.

---

Prerequisites

• A OneSignal account.
• A mobile app with the OneSignal SDK installed and the OneSignalInAppMessages package enabled.

---

Set up an in-app push permission prompt

1. Remove any automatic permission prompts

   Before you begin, make sure your app isn’t already triggering the system permission prompt automatically:

   • Remove any requestPermission() or optIn() calls invoked on app start.
   • Remove native iOS calls to requestAuthorizationWithOptions and any code that generates push tokens directly.
   • Remove Android calls to requestPermissions and any code that generates push tokens directly.
2. Create or edit the in-app message

   Go to Messages > In-App, then either:

   • Edit the default Push Permission Prompt template, or
   • Click New Message to create your own.

   

   Set the audience to Show to all users. OneSignal automatically filters this message to only users who haven’t subscribed to push, based on the Push Permission Prompt click action.

   
3. Customize the message design

   Personalize the look, feel, and wording to fit your app. Tell users what kind of notifications they’ll get and why they’re valuable.

   See Design in-app messages with drag and drop or Design in-app messages with HTML for details.

   
4. Add the Push Permission Prompt click action

   Add a Push Permission Prompt click action to any button or image in your message. When tapped, the system permission prompt appears.

   

   

   If the user has already declined the system permission prompt the maximum number of times (once on iOS, twice on Android), the click action instead sends them to your app’s notification settings. This is equivalent to calling requestPermission(fallbackToSettings: true) from the SDK.

   In-app messages with a Push Permission Prompt click action are not shown to users who have already allowed notifications.

5. Choose a trigger

   The audience controls who is eligible to see the message. Triggers control when it appears.

   

   You can trigger the message:

   • On app open.
   • After a set amount of session time.
   • On a specific user event.
   • Programmatically, using the in-app message trigger SDK methods for full control over timing and context.

   For example, to wait until the user has spent at least 5 minutes in the app:

   
6. Schedule and frequency

   Control how often the message appears:

   • Only once — Low chance of converting users who weren’t ready the first time.
   • Every time conditions are met — Too aggressive and may annoy users.
   • Multiple times (recommended) — Set a high max per user (for example, the maximum value of 9999) with a gap between views (for example, 2 weeks). This re-prompts unsubscribed users periodically without being intrusive. Adjust the gap based on your use case.

   

   Set the message live, monitor your prompt-to-opt-in conversion in the message report, and adjust the gap between displays as needed.

---

Programmatically show the permission prompt

You can trigger the system permission prompt manually using the requestPermission() or optIn() SDK methods. This is useful for custom flows such as:

• A preference center.
• A user profile screen.
• Specific in-app events.

Pass fallbackToSettings: true to requestPermission() so that users who have already declined are redirected to the app’s notification settings instead of silently doing nothing.

If a subscription has been opted out at the SDK level via optOut() (shown as notification_types: -2 on the subscription record), requestPermission() alone will not change the subscription status. Use optIn() instead — it requests permission and clears the opt-out state.

---

Track push permissions and prompt results

• Track which button the user tapped in the soft prompt with the in-app message click listener.
• Track impressions and dismissals (when the user sees but doesn’t tap the soft prompt) with the in-app message lifecycle listener.
• Track the result of the system permission prompt itself with the push permission observer.

You can forward these SDK events to your backend or analytics tool of choice.

---

FAQ

What happens if a user denies the system permission prompt?

On iOS, denying the system permission prompt permanently disables push notifications for your app — the prompt cannot be shown again. On Android, the user gets one more chance (two total). After all attempts are used, the user must re-enable notifications manually in Settings > Notifications on their device. The Push Permission Prompt click action and requestPermission(fallbackToSettings: true) both handle this by sending the user directly to their notification settings.

Can I customize the native system permission prompt?

No. The system permission prompt on iOS and Android is controlled by the operating system and cannot be customized. You can only customize the soft prompt (the in-app message shown before it). Use the soft prompt to explain the value of your notifications, set expectations, and increase the chance of an “Allow” on the system prompt.

Can I still prompt users who have provisional notifications?

Yes. If you use iOS provisional push notifications, you can still show a soft prompt to convert those users to full push subscribers. Time the prompt for a moment when the user has just seen value from a provisional notification — for example, right after they open a notification or act on it.

How do I re-prompt users who previously denied push?

Once the system permission prompt has been exhausted (once on iOS, twice on Android), you cannot show it again. Instead, use the requestPermission(fallbackToSettings: true) SDK method or the Push Permission Prompt click action on an in-app message — both open your app’s notification settings so the user can enable notifications manually. Pair this with an in-app message explaining why notifications are valuable.

Do all Android versions require a system permission prompt?

No — only Android 13 (API level 33) and later. Android 13 introduced the runtime notification permission, requiring explicit user consent for push notifications.

• Released: August 2022 (Pixel devices).
• Required for target SDK: As of August 31, 2023, all new apps and updates on Google Play must target API level 33 or higher.
• Source: Google’s developer guide on notification permissions.

On Android 12 and lower, the app is granted notification permission automatically on install.

---

iOS provisional push notifications

Send notifications to the Notification Center without an upfront permission prompt on iOS 12+.

Mobile SDK reference

requestPermission, optIn, permission observer, and in-app click listener APIs.

Web push permission prompts

Configure soft-prompt, slide-down, and native web push permission requests.

In-app messages setup

Enable in-app messaging in your app so you can run soft prompts.