OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

iOS Push Opt-In Prompt

Prompt iOS mobile app users to subscribe to push the right way.

Apple's Human Interface Guidelines for collecting notification permissions recommends apps "Create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out."

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

Using OneSignal's In-App Messages you can easily create and customize a "soft-prompt" to ask users to grant push permission multiple times.

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

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

Setup The In-App Message

Head to Messages > In-App > New In-App

Set the Message Name to something easy to find in the dashboard and keep the Audience set to "all users". Later we will trigger this message for only iOS devices.

Paid Plans allow targeting segments. You can select "Show to Particular Segment(s)" and Add Segment with Device Type is iOS (you can also include And Session Count > 1 if you want to prompt on the 2nd app open as well, for example).

Setup your message

Depending on your app's theme and how you like to communicate, you can add whatever wording you like to ask your users to subscribe and gauge their interest. For more details on setup see Designing your In-App Message.

Add the Buttons

Create a button for the user to click if they wish to allow notifications. In the button settings, select Add Click Action and Push Permission Prompt (iOS). When the user clicks this button, OneSignal will automatically trigger the native iOS Push Permission Prompt.

Adding a button with this action will prevent this In-App Message from being shown to users who have already granted push permission, unless the In-App Message is manually triggered.

If the user has previously clicked "Don't Allow" on the iOS native Push Permission Prompt, the button will direct the user to the Application Settings in iOS where they can manually enable notifications.

Recommended Setup With Triggers

Under the Triggers section select In-App Trigger and set prompt_ios is true we will add this "key": "value" trigger programmatically in the app with addTrigger method.

Trigger The Prompt

Triggering the prompt in this way will ignore the user's current permission state. Therefore, you should use the getPermissionSubscriptionState method to detect if the device is subscribed or not. If the device is not subscribed, simply use the addTrigger method to show the In-App Message Prompt for iOS.

Make sure the trigger "key" and "value" match what you added to the IAM Trigger. In this example, we used prompt_ios for the key and true for the value.

let status: OSPermissionSubscriptionState = OneSignal.getPermissionSubscriptionState()

let hasPrompted = status.permissionStatus.hasPrompted
print("hasPrompted = \(hasPrompted)")
if hasPrompted == false {
  OneSignal.addTrigger("prompt_ios", withValue: "true")
OSPermissionSubscriptionState* status = [OneSignal getPermissionSubscriptionState];
if status.permissionStatus.hasPrompted == false {
  [OneSignal addTrigger:@"prompt_ios" withVaue:@"true"]
var status = OneSignal.GetPermissionSubscriptionState();
if status.permissionStatus.hasPrompted == false {
  OneSignal.AddTrigger("prompt_ios", "true");
OneSignal.getPermissionSubscriptionState((status) => {
    if status.permissionStatus.hasPrompted == false {
      OneSignal.addTrigger("prompt_ios", "true");
window.plugins.OneSignal.getPermissionSubscriptionState(function(status) {
  if status.permissionStatus.hasPrompted == false {
    OneSignal.addTrigger("prompt_ios", "true");
var status = await OneSignal.shared.getPermissionSubscriptionState();

if !(status.permissionStatus.hasPrompted)
  OneSignal.addTrigger("prompt_ios", "true");

If the prompt isn't showing, check that kOSSettingsKeyAutoPrompt is set to false in the initialization settings and that you have the latest version of the OneSignal SDK in your app.



Any iOS devices that have not been prompted before will now be prompted.

Updated about a month ago

iOS Push Opt-In Prompt

Prompt iOS mobile app users to subscribe to push the right way.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.