Skip to main content

Configuring and Using Push Notifications

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.

NotificationByIdentityRequest

The EnsLib.PushNotifications.IdentityManager.NotificationByIdentityRequestOpens in a new tab class includes the EnsLib.PushNotifications.NotificationInfoOpens in a new tab class and, additionally, specifies the identity registered in the Identity Manager that is to receive the notification.

Property Description
AssociatedAppToken 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.NotificationByIdentityResponseOpens in a new tab 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
NotificationCount 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.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.

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 table of TLS configurations. For example, the configuration name value may be MyAppTLS.

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.DeviceTrackingOpens in a new tab class provides the following methods:

  • AssociateDeviceWithAppToken—Associates a device token, AppID, and service with an AssociatedIdentity string identifier.

  • DisassociateDeviceWithAppToken—Removes the association of the device token, AppID, and service with the AssociatedIdentity string identifier.

  • FindDeviceByAppToken—Finds all devices associated with the specified AssociatedIdentity string identifier. Returns a DeviceTracking object.

  • FindDeviceByDeviceAndAppIds—Finds all devices with the specified device token and AppId. Returns a DeviceTracking object.

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:

    • It sets NotificationInfo to the NotificationInfo in the incoming NotationByIdentityRequest.

    • It sets Identities to the device token in the record.

    • It sets AppId to the AppID in the record, if it is defined.

    • It sets Service to the Service in the record.

  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 production environment, you can use the Push Notifications AppService to get the notification into the InterSystems IRIS® environment. The AppService is a gateway into InterSystems IRIS. To call it, do the following:

  1. Add the AppService to the 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.NotificationRequestOpens in a new tab message.

  4. Call the AppService SendSync method passing the NotificationRequest as the parameter.


Previous sectionPush Notifications Overview
FeedbackOpens in a new tab