Customizing a Push Notification

You can customize the details of a push notification with APNs control fields.

You can use the control fields described in this topic with Push to User and Direct Push notifications. A Push to App notification is not customizable and the default settings of Kii Cloud are applied.

There are some fields for customizing the APNs push notifications. Here we explain some of such fields. For the full coverage, see the Apple official documentation.

In addtion to the control fields below, you can include custom data in a push message and use it in your mobile app. When you design the custom data, keep in mind that the maximum payload size through APNs is 4096 bytes.

Message in Notification Center: aps/alert/body

You can specify a message string shown in Notification Center with the body key included in the alert key or with the alert key itself. If you do not specify any message, nothing will be shown in Notification Center.

If the mobile app is running in the foreground when it receives the push notification, the notification is processed without appearing in Notification Center. Otherwise, the message will be shown in Notification Center. When the user selects the message, the mobile app opens and processes the notification.

The following screenshot indicates that a mobile app, KiiTestApp, received a notification whose alert key has a string of "Hello".

Badge: aps/badge

The badge is the number shown in the upper-right corner of the icon on the home screen. You can set the number in the badge key. The number will be updated when iOS receives the push notification while the mobile app is not running in the foreground. Setting the badge key to a value of 0 or lower removes the badge from the icon.

The specified number will be shown on the badge. If you want to increment the number, calculate the number and specify it.

Sound: aps/sound

Specify the sound to play when iOS receives the push notification with the sound key. Note that the sound will not be played if the mobile app is running in the foreground when it receives the push notification.

The sound must be included in the main application bundle of the target mobile app.

Silent notification: aps/content-available

iOS supports silent notifications. This feature is toggled with the content-available key (its value is always 1). By making notifications silent, the mobile app can directly receive notifications when the app is running in the background. When the mobile app is inactive, however, it cannot receive silent notifications.

To send silent notifications, you must include the content-available key with a value of 1 in the message payload. At the same time, you must exclude the alert, sound, and badge keys from the message payload. If any of the keys is included, the message will not be silent and the user will receive it via Notification Center and so on. Also, you must enable the silent notification feature in Xcode.

The content-available key can be set together with keys such as alert, but bear in mind that a different method will be called at a different timing, especially if you implement an iOS native app. For more information, see Combinations of Reception Methods.

Category: aps/category

You can use categories to specify notification actions.

Define notification actions in the initialization process of the push notification feature and specify the category of the actionable notification in the push message. For the implementation, see Initializing the actionable notification.