Configuring and Using Ensemble Push Notifications
Configuring and Using Push Notifications
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to use Push Notifications services, processes, and operations. This chapter contains the following sections:

Push Notifications Message Types
Push Notifications use the following message types:
NotificationInfo
The EnsLib.PushNotifications.NotificationInfo 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.NotificationRequest class includes the EnsLib.PushNotifications.NotificationInfo 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.NotificationResponse 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.
NotificationByIdentityRequest
The EnsLib.PushNotifications.IdentityManager.NotificationByIdentityRequest class includes the EnsLib.PushNotifications.NotificationInfo class and, additionally, specifies the identity registered in the Identity Manager that is to receive the notification.
Property Description
AssociatedIdentity String that specifies the identity to receive the notification.
The AssociatedIdentity can be any string as long as it is unique in the table. Typically, this is a login name or some other string that identifies a user in the application.
NotificationByIdentityResponse
The EnsLib.PushNotifications.IdentityManager.NotificationByIdentityResponse class returns the number of NotificationRequest messages sent to the target. This is the same as the number of devices registered for the AssociatedIdentity.
Property Description
NotificationResponse Integer that specifies the number of NotificationRequest messages sent to the target of the Identity Manager.
Pushing a Notification Using the APNS Operation
The EnsLib.PushNotifications.APNS.Operation 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 Caché table of SSL configurations. The SSL is associated with the app and must be one provided by Apple for the APNS service. For example, can have the configuration name value: MyAppAppleSSL
ConnectTimeout
SSL 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 SSL is associated with the remote app, but the same SSL is used for every user of the app. If your application is pushing notifications to a single app, you only need one SSL and one APNS operation in your production. If your application is pushing notifications to multiple apps running on Apple devices, you need one SSL for each app and must have one corresponding APNS operation configured with that SSL 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 SSL certificate is supplied by the Apple server. Each app requires a unique SSL.
Pushing a Notification Using the GCM Operation
You configure the following settings on the GCM Operation:
Setting Description
PushServer
URL for the Google Cloud Messaging REST interface. Value is: https://android.googleapis.com/gcm/send
SSLConfig
Configuration name in the Caché table of SSL configurations. For example, can have the value: MyAppSSL
Timeout
REST response timeout period in seconds. Default value: 30
NotificationProtocol
Specifies the GCM notification protocol. Has one of the following values:
  • HTTP—HTTP REST protocol.
  • XMPP—Reserved for future use. The GCM operation does not support the XMPP always connected, bi-directional protocol.
Registering Devices with the Identity Manager
You can register one or more pairs of device tokens and applications with an Associated Identity string identifier. Your application can use this string identifier to push a notification to all the devices associated with the identifier. The EnsLib.PushNotifications.IdentityManager.DeviceTracking class provides the following methods:
Pushing Notifications Using the Identity Manager
When the Identity Manager receives a NotificationByIdentityRequest message it does the following:
  1. It queries the SQL table to find the devices associated with the AssociatedIdentity in the message.
  2. If there are one or more devices returned by the query, it creates a NotificationMessage for each record returned by the query. In the NotificationMessage:
  3. It sends each message to the target component.
Note:
The IdentityManager receives one NotificationByIdentityRequest and creates one NotificationMessage for each associated device. Each NotificationMessage it sends has one device token in the Identities list. Although the GCM server allows you to push a single notification to multiple devices for a user in one call, the IdentityManager does not use this capability. You can send a single notification to multiple GCM devices using the lower-level calls, but not using the IdentityManager.
Using the AppService to Push Notifications
If you are generating your Push Notifications in ObjectScript outside of the Ensemble production environment, you can use the Push Notifications AppService to get the notification into the Ensemble environment. The AppService is a gateway into Ensemble. To call it, do the following:
  1. Add the AppService to the Ensemble production.
  2. Configure the target to send the message to the Identity Manager, a router, or directly to a Push Notifications operation.
  3. In your code, create and populate an EnsLib.PushNotifications.NotificationRequest message.
  4. Call the AppService SendSync method passing the NotificationRequest as the parameter.