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:

  • if present, remove promptForPushNotificationsWithUserResponse method.
  • if present, remove any other reference to iOS native API requestAuthorizationWithOptions.
  • OneSignal SDK 2.x.x set kOSSettingsKeyAutoPrompt to false. 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". Paid Plans allow targeting segments. You can select Show to Particular Segment(s) if you want to only prompt under certain conditions using Segments.

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 see Design 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.

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.

See the IAM Click Actions guide for more details.

Triggers

To show the prompt without code, select the On app open or set the Session Duration trigger to a time of your choosing.

You can also set programmatic triggers when the user clicks a button or visits a certain page of your app for example. Under the Triggers section select In-App Trigger and set prompt_ios is true.

In your app's code, use the OneSignal addTrigger SDK method to show the prompt. For example:

// 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 3.x.x+
OSDeviceState *deviceState = [OneSignal getDeviceState];
BOOL subscribed = deviceState.isSubscribed;
if (subscribed == false) {
    [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");
}
var status = OneSignal.GetPermissionSubscriptionState();
if status.permissionStatus.hasPrompted == false {
  OneSignal.AddTrigger("prompt_ios", "true");
}
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.addTrigger("prompt_ios", "true");
OneSignal.shared.addTrigger("prompt_ios", "true");
private void IdsAvailable(string userID, string pushToken) {
  print("UserID:"  + userID);
  print("pushToken:" + pushToken);
  if pushToken == null {
    OneSignal.AddTrigger("prompt_ios", "true");
  }
}

Schedule and Re-Trigger

Finally, you can schedule the message to start showing after a certain date.

How often do you want to show this message?

If you are testing or using programmatic triggers, we recommend selecting the Every time trigger conditions are satisfied to show it whenever the triggers are met.

If you are using the On app open or Session Duration, try the Multiple times with 9999 and a gap of 1 week in between. The first number is how many times you want the message to show and the 2nd number is the timeframe in which to wait before showing the message again.

In this case, if the user is already subscribed, they will not see the message again until they are unsubscribed.

This can always be changed later based on how often you want to prompt for push.

πŸ‘

Done!

Select Update or Make Message Live.

Any unsubscribed iOS devices 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();

Updated 2 months 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.