Apple Remote Notification

APNs provides a native mechanism to send notifications to the back end. Back-end systems use the Push REST service to notify the mobile platform about notification messages it sends to devices. The mobile platform maps the incoming JSON payload to APNs custom values. For an in-depth list of APNs-specific parameters, see Apple Developer - Generate a Remote Notification

The mobile services push provider for APNs supports two notification types:

1. Visual Notifications are handled without app involvement by the Notification Center when the app is in the background. Notifications are displayed in the lock or home screen based on the system notification configuration for the app. The app can modify the content before it appears in the Notification Center when the flag apns.mutableContent is set.

2. Silent Notifications are handled by the app. The app's notification callback function is called when a new notification arrives. See apns.contentAvailable notification parameter. Message is not guaranteed, see Apple: Pushing background updates to your App. APNs will drop silent notifications when sending too many silent notifications to a device (more than two per hour).

Notification

Note

APNs push provider can be used to send notifications to Apple iPhone, iPod-Touch, Watch or iPad. Some properties are handled by certain device types and OS Versions only.

The mobile services push provider for APNs only maps widely used APNs message properties. Please use the apns.customParameter property if you need an APNs property that isn't available directly.

Example:

{
  "apns": {
    "sound": "default",
    "alertTitle": "Hello World",
    "alertSubtitle": "It's a sunny day",
    "alertBody": "How do you Do?"
  }
}

Common Notification Properties (APNs)

alert (APNs)

The mobile platform maps alert to NS custom value aps.alert. The value of alert can be either a String, or a JSON Object converted to a String.

Limit: The maximum alert text length is 2048 characters.

alert Value as a String

The mobile platform sets alert as value of aps.alert.

alert Value as a JSON Object Converted to a String

The mobile platform parses the String and converts it to a JSON Object. It supports all keys, but we encourage using the relevant apns properties instead.

For example:

{
"alert": "{\"alert_title\": \"This is the title\", \"alert_sub-title\": \"this is the sub-title\", \"alert_body\": \"This is the body\"}}"
}

is forwarded as:

{
 "aps": {
    "alert": {
      "title" : "This is the title",
      "sub-title" : "This is the sub-title",
      "body" : "this is the body"
    }
}

badge (APNs)

The number to display in a badge on your app’s icon. Specify 0 to remove the current badge, if any. For example:

{ "badge": 1 }

is forwarded as:

{ "aps": { "badge": 1 } }

sound (APNs)

The name of a sound file in your app’s main bundle or in the Library/Sounds folder of your app’s container directory. Specify the string default to play the system sound. No sound is played when the property is missing. Please use apns.customSound when sending notifications to APNs and Firebase Messaging.

{ "sound": "chime.aiff" }

is forwarded as:

{ "aps": { "sound": "chime.aiff" } }

Limit: The maximum sound reference length is 256 characters.

data (APNs)

The mobile platform maps data to an APNs custom value using key=data. The value must be a String. For example, the client sends:

{ "data" : "{\"acme1\":\"bar\", \"acme2\" : [\"bang\", \"whiz\" ]}" }

The mobile platform forwards this JSON to APNs:

{ "data": "{\"acme1\":\"bar\", \"acme2\" : [\"bang\", \"whiz\" ]}" }

priority (APNs)

The APNs push provider maps the value normalto 5 and high to 10. Silent push notifications sets the priority from high to normal.

APNs Specific Properties

The push provider for APNs also supports a list of specific APNs message properties directly via apns property. Any property that is not available directly, can be added as a JSON serialized notation in the customPriorities property.

apns.expiry (APNs)

The date at which the notification is no longer valid. This value is a timestamp in ISO 8601 combined date and time presentation. If the value is nonzero and the target is offline, APNs stores the notification and tries to deliver it at least once, repeating the attempt as needed until the specified date.

{ "apns": {
  "expiry": "2007-04-05T12:30:01.001−02:00" }
}

apns.category(APNs)

The notification type. This can be used to define actionable notifications in the device notification center. The notification types and list of actions are defined in the app bundle.

{ "apns": {
  "category": "approve-reject" }
}

is forwarded as:

{ "aps": { "category": "approve-reject" } }

Limit: The maximum category identifier length is 128 characters.

apns.contentAvailable(APNs)

The background notification flag. To perform a silent background update, specify the value true and don't include the alert, badge, or sound keys in your payload.

{ "apns": {
  "contentAvailable": true }
}

is forwarded as:

{ "aps": { "contentAvailable": 1 } }

apns.pushType(APNs)

The push type is used to explicitly define the notification type. Allowed values are:

ALERT, BACKGROUND, VOIP, COMPLICATION, FILEPROVIDER and MDM

apns.topic (APNs)

The topic to be sent along with the APNs notification. If not specified the topic is determined from the certificate.

Limit: The maximum topic identifier length is 256 characters.

apns.customSound(APNs)

The APNs notification sound can be customized by:

• sound: reference to a sound file in /Library/Sounds.
• volume: Playback volume. Value range is from 0.0 (silent) to 1.0 (maximum). The default is 1.0
• critical: The critical alert flag. The default is false.

{ "apns": {
  "customSound": {
    "sound" : "chime.aiff",
    "volume" : 0.9,
    "critical" : true
  }}
}

apns.localizedAlertKey and apns.localizedAlertArguments (APNs)

The localized key value is defined in the iOS application and is used to provide localized alert. The localized message can be enriched by arguments, defined in the localizedAlertArguments property.

{ "apns": {
  "localizedAlertKey": "NEW_PLAYER",
  "localizedAlertArguments": ["John Doe"]
  }
}

is forwarded as:

{ "aps": { "loc-key": "NEW_PLAYER", "loc-args": [ "John Doe"] } }

Limits: The maximum key length is 128 characters, the maximum number of arguments is 16 and the maximum argument text length is 256 characters.

apns.localizedAlertTitleKey and apns.localizedAlertTitleArguments (APNs)

The localized key value is defined in the iOS application and is used to provide localized alert titles. The localized message can be enriched by arguments, defined in the localizedAlertTitleArguments property.

{ "apns": {
  "localizedAlertTitleKey": "NEW_PLAYER",
  "localizedAlertTitleArguments": ["John Doe"]
  }
}

is forwarded as:

{ "aps": { "title-loc-key": "NEW_PLAYER", "title-loc-args": [ "John Doe"] } }

Limits: The maximum key length is 128 characters, the maximum number of arguments is 16 and the maximum argument text length is 256 characters.

apns.localizedAlertSubtitleKey and apns.localizedAlertSubtitleArguments can be used to add a localized alert subtitle to the notification.

apns.alertTitle, apns.alertBody and apns.alertSubtitle (APNs)

These properties define the alert headers and body.

Limits: The maximum title and subtitle text length are 256 characters. The maximum body text length is 2048 characters.

apns.mutableContent (APNs)

The mutable content property controls the message handling in the iOS notification center. The iOS notification center calls the app to enhance the message when it is set to true. This can be used to provide sophisticated messaging. See Apple Developer - Modifying Content in Newly Delivered Notifications for details.

apns.interruptionLevel (APNs)

The interruption level property controls the importance and delivery timing of a notification. Values are passive, active, time-sensitive, or critical.

apns.targetContentId (APNs)

The identifier of the window is brought forward. The value of this key will be populated on the UNNotificationContent object created from the push payload.

apns.relevanceScore (APNs)

The relevance score, a number between 0 and 1, that the system uses to sort the notifications from your app. The highest score gets featured in the notification summary.

Other APNs Properties

The following properties are also passed directly to the aps element.

• launchImageFileName - string value
• showActionButton - Boolean value
• actionButtonLabel - string value
• localizedActionButtonKey - string value
• urlArguments - list of string values
• threadId - string value

Troubleshooting

Message Is Not Received

APNs notification delivery is not always guaranteed. The device may not show or process notifications, even if APNs has accepted the notification, in favor of usability. Common restrictions are:

• Not all visual notifications are shown on the device if multiple notifications are sent in a short time frame.
• None-critical notifications are hidden as soon as the device is in focus mode.
• APNs accepts notifications even if the user has disabled notifications for the app.
• Silent notifications are intended to wake-up the app and perform background activity. The app signals when completed. Silent notifications are dropped when the background processing is still running. The number of silent notifications per hour processed by the app is limited to three.

Please read: Technical-Note: Troubleshooting Push Notifications - Some Notifications Received, but Not All

For in-depth analysis, see Apple's Push Notifications Console. The Apple Push Notification Console sends test notification and shows the delivery log and message status. The aps-unique-id is only available for development/sandbox messages and reported in the Notification Status response

Messages Are Queued Always

The push notification service queues a notification when communication issues with the native push provider occur and tries to resend it with low priority. New notification requests are handled with priority over queued notifications. The service discards the notification after three retries. The native push provider blocks the push service instance when too many notifications, or notifications with errors, are sent. All notification requests are queued and not delivered to the device. This is typical when using a Sandbox APNs configuration with the Productive APNs Endpoint (or vice versa), or when using a server certificate with an incorrect bundle ID. You must rotate the server certificate after fixing your configuration.

Verify the device token by using the Apple Push Console Device Token Validator, see. Observe the reported environment for the device push token:

• Development: The signing profile is used during development. Select Sandbox.
• Production: Select Production for Mobile Apps that are distributed via Device Management or Apple App Store.

The validator returns Device Token is invalid when the device token doesn't match the signing profile bundle identifier and push configuration.

---

Last update: July 30, 2024