Advanced version of push notification Part — 2 — Notification Payload.

This article is another push notification series article which is going to cover about the notification payload, what are the options available? and how to use them in our iOS app?

The payload is a JSON format data which contains a predefined value which will be handled by apple(like add the headline, message, play sound, add the banner, category etc) and we can define the custom values, which we use for our purposes. APNS Payload should have 46Kb(4096 Bytes) size, if it’s exceeded the size apple will reject it from the APNs side and throw an error.

Alert

You might have noticed in the previous articles I’ve used the alert as object and single value.

This article I used as single value

How to send notification to device without server configuration.

This article I used as object

How to test push notification in Simulator

Alert in notification payload

In the beginning stage apple only supports alert as a string value then they give the support as the object. If you set the alert as a string then apple will use that as body, but if we send it as an object then the push notification alert will have a title and message from alert object.

Let test with our test app and see what it looks like.

Alert String Vs Object

Sound and Badge

Badge

If your app wants to support the badge, first we need to add this UNAuthorizationOptions when ask the user’s permission for the sending push notification, once we asked the permission we can add it as an integer in the notification payload, based on the number in the payload the number will be displayed on top of the app icon.

Notification with badge

Sound

Sound is used in two purposes. This is also same as badge need ask the user’s permission using UNAuthorizationOptions when ask the request.

1. If you want to customize the notification sound, you can add the local file name in the payload. But the file name should be .caf file format.

Notification with local sound

2. If your app is supporting the critical notification as one of the UNAuthorizationOptions then sound is used as object.

Based on the notification payload we are setting the custom notification sound file from local, set the critical as 1 and the sound level as 0.75(sound range from 0–1)

Critical alert with sound

Grouping Notification

Another option provided by apple is to group the notifications in the notification Center. To keep the same notifications as the group we need to maintain the same Id for them, it’s called thread-id. This is usually maintained by the backend since these values changed based on the notifications. So for testing purposes, I’m going to use random values.

Please take note of ⚠️:

1. This is should be added inside the aps object as a new value
2. It should be a string value
3. The key should be thread-id

This feature is usually used in games and sports-related apps because we need to group them based on the games. For this example, I’m a fan of cricket so I’m going to use the cricket news. Assume two matches are going on one is India Vs England other one is Sri Lanka Vs Australia

So the app is going to receive the notification from both matches and by using these features we are going to group them based on the matches.

Two notification with same thread Id — Ind Vs Eng

After send both push notification

Sri Lanka Vs Australia push notification

After send 4 of these notification, the notifications are grouped based on the thread-id. So this will help the user to see the notifications together.

After send both group notifications SL vs Aus and Ind Vs Eng

Localization

When it comes to multi-language support, the user can change the app or system language at any time, so the notification also should be changed according to the language user has chosen

There are two alternative ways to send the notification

1. Send the user-chosen language to the backend, so the backend checks the previously chosen language and based on that the notification payload will be created at the backend level and sent it to the user.
2. The localised file will be stored inside the app and based on the localized string, the notification will fetch the string from the localised string file and display it to the user. But this has some problem, we can’t expect all the localized string can be stored inside the app, because if your app always has the static strings in the push notifications then it’s fine but if the app is supporting the dynamic push notification then this option is not a good idea.

This section is only going to explain how the payload should be looks like for the 2nd scenario, first one is based on the system design so this article is not going to explain how that can be done.

When it comes to the local localizable string file support, the payload object names are different compared to the traditional push notification payload.

The object details for localizable push notification payload

localizable string sample payload

Update existing Notification

When it comes to the game applications, sometimes we might need to modify the existing push notification instead of sending lots of push notifications. If we send lots of push notifications the user might get annoy.

This updating the push notification can be achieved using apns-collapse-id, which needs to pass it to APNS server through HTTP header(Don’t ask me why that’s how apple has configured, I’m also wondering why apple is not including this in the payload itself )

apns-collapse-id is a unique identification for the notification, so if we use the same id again and send a push notification the existing notification with the same id will get modified instead of sending a new push.

Send push with collapse Id

After updated the push notification

Based on the above setup in the Push Notification Tester app, the unique id is given for the collapse Id. In order to test this scenario, the title has modified in the second time. After click the send button the existing notification will get modify as given the second title value.

Background Notification

Sometimes the app might change the icons remotely based on the festival or events, for those without releasing a new build to all the users, we should be able to achieve using background notification. To support the background notification,

1. App should configured with Background Modes capabilities
2. We should configure one delegate function called application(_:didReceiveRemoteNotification:fetchCompletionHandler:)
3. Notification payload should have new param called content-available as 1

Capabilities setup for background notification

Background notification payload

Please take note ⚠️

1. content-available 0 means it’s not a usual notification, So if you want to support the background notification, please use this object otherwise ignore this.
2. iOS will wake up the app from the background and give it up to 30 secs to execute or complete the actions, so make sure the app is having the minimal amount of work necessary so that it can complete the action within 30Sec
3. We can even send the notification alert object with title and body, which will also get displayed and based on the customs value you can configure the app to do the background process
4. If the app is in the terminated state the functionalities which we added in the background notification receive delegate function, so the app should run in the background.
5. We can’t make sure 100% the background task work will be get finished as expected, it’s depends on the OS.

Conclusion

We have reached the advanced version of the push notification payload article, hope you learned new stuff. Please give some claps(👏) and comments that will boost me to write more articles. Next article from the push notification series, I’ll be writing an article which is going to explain how can you add actions in the push notification like having the button. Keep in touch for the next article

Happy coding…..

The latest code and all type of payload can be found from this GitHub repo

GitHub - Achsuthan/iOSPushNotificationMediumArticle at pushPayloads