Notify: New APNS Message Format

Notify: New APNS Message Format

• New default APNS message format from Oct 30th.
• Services created before Oct 30th will continue with current message format.
• Developers can take advantage of the Title Attribute.
• Easier to use Notify for web push targeting Safari browsers on OS X.

Starting from October 30th, 2017, for all new Notify Services, we will change the default message format sent to iOS devices via APNS. Services that will have been created before October 30th, will continue to use the current message format. Developers that want to keep using the old message format for new Services as well, can continue to do so.

So what exactly is changing? We will change the type of the aps.alert attribute from string to object. This will allow developers to take advantage of the title attribute and makes it easier to use Notify for web push targeting Safari browsers on OS X.

What is the title attribute we speak of?

In the screenshot below, you’ll find that the News App has sent a notification with the title “News Top Stories”. All other apps have simply sent notifications without titles. The title attribute essentially allows us to send messages with the title.

The old message format was limited in the sense that even if a title parameter was provided, it wouldn’t be a part of the message payload.

The old message format looked like this (regardless of whether the Title parameter is present or not):

The new message format is:

In order to help developers migrate, we apply the Notification Protocol Version feature of Notify. For each notification sent, our system determines the right message format on an address by address (i.e. Binding by Binding) basis. This message format is controlled by the applicable Notification Protocol Version.

The old message format corresponds to protocol version 3 and the new one to 4.

The Notification Protocol Version can be configured separately for each binding using the NotificationProtocolVersion parameter while creating a binding using the REST API. It can also be configured for the Service as a whole using the DefaultApnNotificationProtocolVersion. The default value of this parameter for all new services will be changed from 3 to 4.

What this means for developers:

1: If you want to keep everything as is and you do not create new Services:

Do nothing, you are all set.

2: If you want to keep everything as is and you do create new Services:

Make sure you set the DefaultApnNotificationProtocolVersion parameter to 3 in your Create Service API requests. 

3: If you want to try the new protocol on new Services prior to October 30th:

Set DefaultApnNotificationProtocolVersion parameter to 4 in your Create Service API request (not available via the console).

4: If you want to gradually roll out a new app version that supports the new protocol in an existing Service:

Set NotificationProtocolVersion in Create Binding request for new app versions.

To summarize:

• If you are not creating new Services, do nothing, you are not affected
• If you are creating new Services regularly, check out case 2 above.

If you are still unsure, just send us your question.