iOS Push Opt-In Prompt

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:

remove promptForPushNotificationsWithUserResponse method
remove any other reference to iOS native API requestAuthorizationWithOptions
OneSignal SDK 2.x.x set kOSSettingsKeyAutoPrompt to false. See the initialization settings for details. OneSignal SDK 3.x.x does not have this option.

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

Setup 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 "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 AND Session Count greater than 1 if you want to prompt on the 2nd app open for example.

Setup 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 on setup see Designing your In-App Message.

Add the Buttons

If not using the default template, create a button and 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 as we will see below.

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

Use the permission status parameter from getDeviceState 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.

// OneSignal iOS SDK 3.x.x
if let deviceState = OneSignal.getDeviceState() {
  let subscribed = deviceState.isSubscribed
  if subscribed == false {
    OneSignal.addTrigger("prompt_ios", withValue: "true")
  }
 }

// OneSignal iOS SDK 2.x.x
let permissionStatus = OneSignal.getDeviceState().notificationPermissionStatus
print("permissionStatus = \(permissionStatus)")
if permissionStatus == OSNotificationPermission.notDetermined {
  OneSignal.addTrigger("prompt_ios", withValue: "true")
}

// OneSignal iOS SDK 3.x.x
OSDeviceState *deviceState = [OneSignal getDeviceState];
BOOL subscribed = deviceState.isSubscribed;
if (subscribed == false) {
    [OneSignal addTrigger:@"prompt_ios" withValue:@"true"];
}

// OneSignal iOS SDK 2.x.x
OSNotificationPermission status = [OneSignal getDeviceState].notificationPermissionStatus;
if (status == OSNotificationPermissionNotDetermined) {
    [OneSignal addTrigger:@"prompt_ios" withValue:@"true"];
}

// OneSignal React Native SDK 4.x.x
const deviceState = OneSignal.getDeviceState();
if (deviceState.isSubscribed == false) {
  OneSignal.addTrigger("prompt_ios", "true");
}


// OneSignal React Native SDK 3.x.x
const { notificationPermissionStatus } = await OneSignal.getDeviceState();

if (notificationPermissionStatus === 0) {
  OneSignal.addTrigger("prompt_ios", "true");
}

/*
(Pre-major release documentation)
You should use the `getPermissionSubscriptionState` [method](doc:sdk-reference#getpermissionsubscriptionstate-method) to detect if the device is subscribed or not. If the device is not subscribed, simply use the `addTrigger` [method](doc:sdk-reference#in-app-messages) 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.
*/

var status = OneSignal.GetPermissionSubscriptionState();
if status.permissionStatus.hasPrompted == false {
  OneSignal.AddTrigger("prompt_ios", "true");
}

/*
(Pre-major release documentation)
You should use the `getPermissionSubscriptionState` [method](doc:sdk-reference#getpermissionsubscriptionstate-method) to detect if the device is subscribed or not. If the device is not subscribed, simply use the `addTrigger` [method](doc:sdk-reference#in-app-messages) 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.
*/

window.plugins.OneSignal.getPermissionSubscriptionState(function(status) {
  if status.permissionStatus.hasPrompted == false {
    OneSignal.addTrigger("prompt_ios", "true");
  }
});

/*
(Pre-major release documentation)
You should use the `getPermissionSubscriptionState` [method](doc:sdk-reference#getpermissionsubscriptionstate-method) to detect if the device is subscribed or not. If the device is not subscribed, simply use the `addTrigger` [method](doc:sdk-reference#in-app-messages) 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.
*/
var status = await OneSignal.shared.getPermissionSubscriptionState();

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

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

Programmatically Triggering the Native iOS Permission Prompt

Not Recommended: use the below OneSignal method to trigger the Native iOS Permission Prompt. It is recommended to use the above or your own soft-prompt first before triggering this method.

// Call when you want to prompt the user to accept push notifications.
//Major Release iOS 3.x.x
OneSignal.promptForPushNotifications(userResponse: { accepted in
   print("User accepted notifications: ", accepted)
   //set to true to fallback to app settings
}, fallbackToSettings: true)

// iOS SDK 2.x.x
// Only call once and only if you set kOSSettingsKeyAutoPrompt in AppDelegate to false.
OneSignal.promptForPushNotifications(userResponse: { accepted in
   print("User accepted notifications: \(accepted)")
})

[OneSignal promptForPushNotificationsWithUserResponse:^(BOOL accepted) {
  NSLog(@"Accepted Notifications?: %d", accepted);
}];

OneSignal.PromptForPushNotificationsWithUserResponse(OneSignal_promptForPushNotificationsResponse);

private void OneSignal_promptForPushNotificationsResponse(bool accepted) {
  Debug.Log("OneSignal_promptForPushNotificationsResponse: " + accepted);
}

// Calling registerForPushNotifications
OneSignal.promptForPushNotificationsWithUserResponse(myCallback);

function myCallback(permission){
    // do something with permission value
}

await OneSignal.shared.promptUserForPushNotificationPermission(fallbackToSettings: true);

window.plugins.OneSignal.promptForPushNotificationsWithUserResponse(function(accepted) {
  console.log("User accepted notifications: " + accepted);
});

OneSignal.Current.RegisterForPushNotifications();

Setup The In-App Message

Setup your message

Add the Buttons

Recommended Setup With Triggers

Trigger The Prompt

👍Done!

Programmatically Triggering the Native iOS Permission Prompt

👍
Done!