Skip to main content
A push permission prompt is the operating system dialog that asks users whether your app can send push notifications. Their answer determines whether you can deliver notifications that appear as banners, show on the lock screen, and play sounds.
iOS and Android system permission prompts side by side
Treat prompting as a strategy. The system prompt can only be shown a limited number of times: once on iOS and twice on Android (Google and Huawei). If the user declines every attempt, they must manually re-enable notifications in system settings. A poorly timed prompt can permanently cost you a subscriber, and reachable audience is the biggest lever on the ROI of every push campaign you run. 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. This guide covers mobile app push. For web push, see Web push permission prompts.

​
Strategy for a high opt-in rate

Push opt-in rates depend far more on when and how you ask than on what the system prompt itself says. Apps that treat prompting as a strategy consistently outperform apps that prompt on first launch. The principles below are the building blocks. The example strategy below shows how to combine them into a concrete playbook.

​
Principles

  • Ask after a value moment. Wait until the user has just experienced something notification-worthy: completing onboarding, saving an item, following a topic, placing an order, or finishing a first session. Prompting on first launch, before the user understands what your app does, is the single biggest cause of low opt-in rates.
  • Start with provisional notifications on iOS. Provisional notifications deliver quietly to the Notification Center without any prompt, so users decide whether to keep them based on real content instead of a hypothetical explanation. This is often the highest-conversion path on iOS and should be your default starting point.
  • Explain the value with an in-app soft prompt. A soft prompt is a OneSignal in-app message that tells users what kind of notifications you’ll send and why they matter. Dismissing a soft prompt does not consume a system prompt attempt, so you can re-ask users who were not ready.
  • Re-ask users who declined the soft prompt, not the system prompt. Configure the soft prompt to re-show on a cadence (for example, every 2 weeks). Users who were not ready get another chance without exhausting the system prompt limit.
  • Iterate on copy and timing. Ship the soft prompt, watch the conversion in the message report, then adjust the trigger, wording, and frequency. Small changes to timing and copy routinely shift opt-in rates by tens of percentage points.

​
Example: onboarding opt-in strategy

This example combines provisional notifications for immediate iOS reach with a soft prompt at a value moment for full opt-in. Use it as a starting point and adapt the notification types and value moments to your app. For Android and Huawei apps, skip phase 1 and start at phase 2. Phase 1: Silent reach on iOS
  1. Turn on provisional authorization in the OneSignal dashboard under Settings > Apple iOS > Advanced Configuration > Enable iOS 12 direct to history.
  2. Send 2 to 3 high-quality notifications during the user’s first week. Pick content that demonstrates the value of subscribing: a personalized recommendation, a breaking-news alert, or a weekly digest. Users receive them silently in the Notification Center with no prompt.
Phase 2: Convert at a value moment
  1. In Messages > In-App, create a soft prompt that references the value the user has already experienced. Example headline: “Get breaking news alerts on your lock screen.”
  2. Set the audience to Show to all users. The Push Permission Prompt click action filters to unsubscribed users automatically.
  3. Trigger the message on a high-signal event: opening or acting on a provisional notification, following a topic, adding an item to a cart, or 5 minutes of session time.
  4. Add a Push Permission Prompt click action to the CTA button.
  5. Set the schedule to Multiple times with max per user 20 and a gap between views of 2 weeks (about 10 months of re-prompting).
Phase 3: Measure and iterate
  1. After 1 to 2 weeks, check the message report for prompt-to-opt-in conversion.
  2. Instrument the full funnel with the SDK listeners: soft prompt clicks, dismissals, and the system prompt outcome. Forward the events to your analytics tool.
  3. Adjust one variable at a time (trigger event, headline, CTA copy, or gap between displays) based on the numbers.
Trigger the soft prompt right after a user opens or acts on a provisional notification. They have already seen value from your notifications, which lifts the “Allow” rate on the system prompt significantly.

​
Choose an approach

You have three ways to grow your push subscriber base with OneSignal. Most iOS apps should combine provisional notifications with an in-app soft prompt; most Android apps should start with the soft prompt.
ApproachPlatformsHow it worksWhen to use
In-app soft prompt (recommended)iOS, Android, HuaweiConfigure a OneSignal in-app message with a Push Permission Prompt click action. Tapping the button shows the system prompt. Dismissing the in-app message consumes nothing, so you can ask again later.The default choice. Lets you design, schedule, target, and re-show the prompt without a code release.
Programmatic promptiOS, Android, HuaweiCall requestPermission() or optIn() from your app code. The system prompt appears immediately.Custom flows where your app owns the trigger: preference centers, profile screens, or in-app events that warrant a prompt.
Provisional notificationsiOSEnable in the OneSignal dashboard. Users receive quiet notifications in the Notification Center without any prompt and convert to full subscribers by tapping Keep.iOS onboarding and low-friction reach. Combine with a soft prompt to convert quiet subscribers into full push subscribers.
All three can be combined. A common high-performing pattern on iOS is to enable provisional for immediate quiet reach, show a soft prompt at a value moment, and expose a programmatic prompt from a preference center for users who want to opt in on demand.
In-app message leading to system push permission prompt

​
Prerequisites

​
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.
OneSignal in-app messages list showing the Push Permission Prompt template
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.
Audience setting configured to show to all users
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.
In-app message block editor with a push opt-in prompt
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.
Click action dropdown with Push Permission Prompt selected
iOS native push notification permission prompt
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. Aim to trigger the prompt at a value moment: a point where the user has just experienced something notification-worthy.
In-app message trigger configuration panel
Trigger options, ordered roughly from lowest to highest conversion:
  • On app open. Simple, but rarely optimal. Use only if the app’s value is obvious within seconds.
  • After a set amount of session time. A good default. Waits until the user has explored the app before asking.
  • On a specific user event. Best for conversion. Trigger after high-signal actions like completing onboarding, saving an item, following a topic, or finishing a first purchase.
  • Programmatically, using the in-app message trigger SDK methods. Full control over timing and context, including combining multiple signals before you prompt.
For example, to wait until the user has spent at least 5 minutes in the app:
Session duration trigger set to 5 minutes
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 max per user with a gap between views. For example, 20 displays with a 2 weeks gap re-prompts unsubscribed users for about 10 months at an aggressive cadence. Loosen the gap (for example, 30 days or 60 days) for lower-engagement or utility apps where a 2-week cadence feels pushy.
Schedule configuration showing max displays and gap between views

​
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: 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.

​
Use iOS provisional notifications

Provisional push notifications were introduced in iOS 12. They let you deliver notifications to the Notification Center without showing a permission prompt. Users see real content from your app and decide whether to keep, silence, or turn off notifications based on that experience. Why it works as a strategy:
  • No system prompt to fail. You can start reaching users on their first session without any upfront opt-in decision.
  • Users decide based on real value, not a hypothetical explanation.
  • You can still show a soft prompt later to convert provisional users into full push subscribers with banners, sound, and lock-screen alerts.
Trade-offs. Provisional notifications have reduced visibility. They deliver quietly to the Notification Center only: no banner, no sound, and no lock-screen alert until the user upgrades to full permission.
iOS provisional push notification with Keep and Turn Off options
To turn on provisional authorization, go to the OneSignal dashboard under Settings > Apple iOS > Advanced Configuration and check Enable iOS 12 direct to history. For the full walkthrough, including how users interact with provisional notifications and how they combine with the standard prompt, see iOS provisional push notifications.
For a concrete playbook that pairs provisional notifications with a soft prompt at a value moment, see the example onboarding opt-in strategy.

​
Track push permissions and prompt results

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, and you should. Provisional users are prime candidates for a soft prompt because they have already seen real notifications from your app. See Use iOS provisional notifications for the recommended pattern. Time the soft prompt for right after the user opens or acts on a provisional notification.

​
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. 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.