iOS Customizations

iOS features OneSignal SDK supports

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 subscriber, they will be directly sent to the Notification Center.

See iOS: Provisional Push Notifications for details.

App Name

Set as the Display Name in Xcode. Changing your app name will require users to restart the device to get the new name.

Notification Icons

Apple uses your App's Icon as the main notification icon. In iOS 15, Apple introduced Communication Notifications which "provide a rich experience for direct communications." You can enable Communication Notifications following Apple's guide.

Notification Grouping

See Notification Grouping for details.

Customize iOS Push Payload

The OneSignal Push Payload contains a "custom" key with nested "i" value (which contains the OneSignal Notification Id) and "a" value which is the data or "additional data" sent in the push. More details on this in our Service Extensions Guide.

Here is how the notification payload should look through the NSE using our "custom" key for additional data:

  "aps": {
      "title" : "Note title",
      "body" : "notification message"
    "badge" : 5
  "ios_data_key1" : "bar",
  "ios_data_key2" : [ "bang",  "whiz" ],
  "custom": {
    "a": {"key": "value"},
    "i": "xxxx"

The ios_data_keys can be a used for your own additional data keys if you turn on additional_data_is_root_payload with our Update an app API.

Image Carousel and Notification Content Extensions

iOS provides a UNNotificationContentExtension protocol as the entry point for a notification content app extension. This can be used to display a custom interface for your app’s notifications. See iOS: Image Carousel Push Notifications for an example guide on how to use this for creating a carousel within an iOS notification.

Critical Alerts

See iOS: Focus Modes and Interruption Levels for details.