Expand Collapse
Just a second...

Push notification JSON format

When a topic is updated. The Push Notification Bridge sends a notification through either APNS or GCM. This message is in JSON format. You can define the format of the message in a template in the PushNotifications.xml configuration file. If the update is in the correct JSON format, you can relay the update verbatim to the push notification network.

Using templates

Templates are configured in the PushNotification.xml file. These templates are associated with specific topics. When a topic is updated, the associated template is applied to that update before the update is sent through the push notification network. The template uses the following placeholders to include topic and update information in the notification message:
${topic.path}
The path that the update is received on.
${topic.update}
The content of the update.

A template notification message can include both an apns section and a gcm section. The size of the data within each of these sections is restricted by the push notification network and currently cannot be greater than 2 KB.

After the update is transformed by the template, only the section of the notification message that is in the appropriate format for that push notification network is passed to the push notification network to be sent on to the client.

Verbatim relay

You can also specify that topic updates be passed to the push notification network verbatim. In this case, it is the responsibility of the client or publisher updating the topic to ensure that the update content is in the correct JSON format. If the update content is not in the correct JSON format, the Push Notification Bridge logs an error.

If there is no matching template, verbatim relay is the default.

APNs

The apns section wraps Apple's JSON format for an APNs message. For more information, see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html

The apns section of the transformed notification message is used when the destination URI starts with apns:// and the notification is sent through the Apple Push Notification Service

    "apns": {
        "aps": {
            "alert": {
                "title": "notification_title",
                "body": "notification_content"
            }
        },
        User-defined key-value pairs
    }

GCM

The gcm segment is a representation of Google's package com.google.android.gcm.server, which defines the following headers:
collapseKey
A unique identifier for a group of notifications that can be collapsed. When an idle device becomes active again, only the most recent notification for any given collapse key is sent.

For example, the topic path of the topic that the bridge subscribes to can be used as the collapse key and inactive devices are sent only the most recent update to that topic when they become active again.

Note: A maximum of 4 different collapse keys are stored simultaneously by GCM.
delayWhileIdle
When the value of this field is set to true, notifications are not be sent until the device becomes active. The default value is false.
dryRun
When the value of this field is set to true, you can test a request without actually sending a message. The default value is false.
timeToLive
How long in seconds the notification is kept in GCM storage if the device is offline. The maximum time to live supported is 4 weeks.
The gcm segment also contains a data section that contains a JSON payload. This JSON payload must be a dictionary of key-value pairs where both the key and the value are strings.

The gcm section of the transformed notification message is used when the destination URI starts with gcm:// and the notification is sent through the Google Cloud Messaging

    "gcm": {
        "collapseKey": "group_identifier",
        "delayWhileIdle": boolean,
        "timeToLive": integer,
        "data": {
                User-defined key-value pairs
        }
    }

Notification message example

The following example shows the results of an online auction being sent as a push notification in both APNs and GCM format.

{
    "apns": {
        "aps": {
            "alert": {
                "title": "Auction Result",
                "body": "You won the auction for 'Antique oak table'"
            }
        },
        "auctionID": "abc123xyz789",
        "auctionConclusion": 123456789
    },
    "gcm": {
        "collapseKey": "abc123xyz789",
        "delayWhileIdle": false,
        "timeToLive": 60,
        "data": {
            "result": "You won the auction for 'Antique oak table'",
            "auctionID": "abc123xyz789",
            "auctionConclusion": 123456789
        }
    }
}

This page last modified: 2018/04/06