This chapter describes how to use Push Notifications services, processes, and operations.
Push Notifications Message Types
Push Notifications use the following message types:
NotificationInfo
The EnsLib.PushNotifications.NotificationInfoOpens in a new tab class contains the information that is in the notification that is pushed to the device.
Property |
Description |
AlertNotification |
String to be displayed to the user as a notification. |
BadgeNotification |
Integer that is displayed to the user in an icon. For example, this can be used to indicate the number of unread messages. |
SoundNotification |
String that identifies a sound to be played on the device. |
ExpiresUTC |
Timestamp that indicates when the notification expires. If the notification is not delivered to the device by this time, the server will not send it to the device. |
Data |
String containing name-value pairs in JSON form. Data contains the names and values that are used by the notification handling code in the mobile app. |
UrlNotification |
Reserved for future use. |
CollapseKey |
Reserved for future use. |
NotificationRequest
The EnsLib.PushNotifications.NotificationRequestOpens in a new tab class includes the EnsLib.PushNotifications.NotificationInfoOpens in a new tab class and, additionally, specifies the device(s) to receive the notification.
Property |
Description |
AppIdentifier |
String that is only used for GCM notifications and identifies the App that the notification is associated with. |
Identifiers |
String that specifies the device that are to get the notification. For APNS, the device is specified by a device token. For GCM, the device is specified as a registration ID. |
Service |
Identifies whether the device is a GCM or APNS device. Service has a value of “GCM” or “APNS”. |
NotificationResponse
The EnsLib.PushNotifications.NotificationResponseOpens in a new tab class contains the information returned from the APNS or GCN server.
Property |
Description |
DeliveredAtUTC |
Timestamp that specifies the time that the notification was sent to the APNS or GCM server. |
MessageIds |
String that contains a list of message Ids returned by the server. |
MulticastId |
String that contains the multicast Id returned by GCM server. |
Pushing a Notification Using the APNS Operation
The EnsLib.PushNotifications.APNS.OperationOpens in a new tab sends the notification request to the APNS server to forward to the specified device. The APNS server pushes the notification to one device for each call. It does not return any information other than if an error occurs, an indication that the error has occurred.
You configure the following settings on the APNS Operation:
Setting |
Description |
PushServerAddress |
Hostname of the Apple Push Notification Server. Value is: gateway.sandbox.push.apple.com |
PushServerPort |
Port for the Apple Push Notification Server interface. Value is: 2195 |
SSLConfig |
Configuration name in the table of TLS configurations. The TLS configuration is associated with the app and must be one provided by Apple for the APNS service. For example, the configuration name value may be MyAppAppleTLS. |
ConnectTimeout |
TLS connection timeout period in seconds. The connection is terminated after this period of inactivity. Default value: 30 |
ResponseTimeout |
Time period in seconds to wait for a response to a connection request. Default value: 5 |
NotificationProtocol |
Specifies the APNS notification protocol. Has one of the following values:
-
Simple—Simple Notification Protocol, which does not return any value and does not notify you if the protocol message causes an error.
-
Enhanced— Enhanced Notification Protocol, which returns values if the protocol message contains an error. This protocol does not return a value for messages without errors.
-
Modern—Reserved for future use. The APNS operation does not support the Modern Notification Protocol.
|
The TLS configuration is associated with the remote app, but the same TLS configuration is used for every user of the app. If your application is pushing notifications to a single app, you only need one TLS configuration and one APNS operation in your production. If your application is pushing notifications to multiple apps running on Apple devices, you need one TLS configuration for each app and must have one corresponding APNS operation associated with that TLS configuration for each different app. Note that if you are using a router, you must direct each notification to the correct APNS operation. For example, you could create a lookup table that relates the device token to its corresponding operation and then use that lookup table in a routing rule.
The APNS protocol does not return any values other than error statuses for the Enhanced protocol. Consequently, the only way to detect that an Enhanced protocol message has not failed is to wait to detect a return error response. If no error response is received in a reasonable time, the operation assumes that the protocol message has succeeded. You specify the time to wait for an error response in the ResponseTimeout setting. The value should be long enough to capture any error response from the APNS server, but since it cannot handle another request until after the time out, the value should not be any longer than needed. With the default value of 5 seconds, an operation instance can only handle one request every 5 seconds; consequently, you should set the pool size large enough to handle the number of requests that typically occur within the time out period.
If you are using the Simple protocol, it does not return any value even if there is an error. With the Simple protocol, there is no advantage in setting ResponseTimeout to anything other than the minimum value or 0 seconds.
The TLS certificate is supplied by the Apple server. Each app requires a unique certificate.