iOS Customizations

Provisional Push Notifications

iOS 12 introduced Provisional aka Direct-To-History push notification authorization. This means that instead of having to prompt the user for permission to send them push notifications, your app can request provisional authorization. Some details about these push notifications:

• they will not show a banner
• they will not play a sound
• they will not alert the user, they will be directly sent to the Notification Center.

If you Keep... the notification, you have the options:

• "Deliver Prominently" which subscribes the user to regular push notifications with banners and sounds
• "Continue Delivering Quietly" which will keep push notifications silent and will stay like this. It will also remove the options to "Keep..." or "Turn off...".

You can still prompt the user to subscribe normally to push even with these turned on or turned off.

To enable or disable provisional authorization for your app, go to your OneSignal dashboard Settings > Apple iOS > Advanced Configuration > Enable iOS 12 direct to history option for your app (which currently requires using the OneSignal SDK 2.9.0 or newer).

To disable this, just uncheck the box (unchecked by default).

🚧

Provisional vs. Normal Authorization

Once you enable provisional notifications for your app, iOS 12 users will automatically be authorized the next time they launch the app.

However, your application can still request push notification permissions in the traditional way, which will still cause the permission prompt to be shown to the user.

In addition, if your app does not set the kOSSettingsKeyAutoPrompt iOS setting to false during init(), the SDK will still show the normal permission prompt, and your app will not get provisional permission.

Once you've enabled direct to history in the Dashboard, our SDK will automatically request provisional authorization and you will be able to send push notifications to these users.

However, if you only want to request provisional authorization in only some situations, you can also use a new method in our SDK:

OneSignal.registerForProvisionalAuthorization({ accepted in
    //handle authorization
})

[OneSignal registerForProvisionalAuthorization:^(BOOL accepted) {
    //handle authorization
}];

Update App Title In Push

If you changed your app name and/or would like to change the App Title, simply update the "Display Name" in Xcode for the main app target and release an app update.

Devices will see push containing the new App Title once they restart the device.

Critical Alerts

This requires you to obtain special permission from Apple before being able to send Critical Alerts. Once you obtain this permission, you can follow the below guide to send Critical Alerts (updated thanks to this answer by MillerMedia on stackoverflow):

1. Setup the OneSignal iOS SDK with the Notification Service Extension

You will need to implement the Notification Service Extension as outlined in our Mobile Push Quickstart for the SDK you use.

2. Update OneSignal App Payload Structure for iOS

Using our Update an app API, set additional_data_is_root_payload to "true"

Example update call:

• requires your User Auth Key and App ID

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic YOUR_USER_AUTH_KEY" \
     --data-binary "{
\"additional_data_is_root_payload\": true}" \
     https://onesignal.com/api/v1/apps/YOUR_APP_ID

3. Add the Critical alerts "sound" parameter

Critical Alerts requires the "sound" parameter to be passed as a dictionary to the API calls. In your requests, set mutable_content to true and use our data parameter to add your "CRITICAL" flag, like data: {"CRITICAL": "TEST"}

In the notification category extension, you can look for this:

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.receivedRequest = request;
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
    
    // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is excuting
    //            Note, this extension only runs when mutable-content is set
    //            Setting an attachment or action buttons automatically adds this
    // NSLog(@"Running NotificationServiceExtension");
    // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];
  if ([request.content.userInfo[@"CRITICAL"] isEqualToString: @"TEST"]) {
    [self.bestAttemptContent setSound:[UNNotificationSound
     criticalSoundNamed:@"Alarm.wav" withAudioVolume:1.0]];
  }
  self.contentHandler(self.bestAttemptContent);
}

override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    self.receivedRequest = request;
    self.contentHandler = contentHandler
    bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

    if let bestAttemptContent = bestAttemptContent {
        OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: self.bestAttemptContent)
      if ((request.content.userInfo["CRITICAL"] as? String) == "TEST"){
        bestAttemptContent.sound = UNNotificationSound.defaultCriticalSound(withAudioVolume: 1.0)
      }
      contentHandler(bestAttemptContent)
    }
}

Notification Grouping

With iOS 12+ Apple introduced the concept of grouping notifications with specific "thread ids" along with adding a summary and how many notifications within that summary.

These parameters can be set directly into the notification payload from the OneSignal API using the thread_id, summary_arg, and summary_arg_count parameters.