Configuring and Using Push Notifications

Push Notifications Message Types

Push Notifications use the following message types:

• EnsLib.PushNotifications.NotificationInfo—contains the information sent to the mobile device.

• EnsLib.PushNotifications.NotificationRequest—contains the NotificationInfo plus routing information that allows the operation to send it to the correct device.

• EnsLib.PushNotifications.NotificationResponse—contains the response from the notification server.

• EnsLib.PushNotifications.IdentityManager.NotificationByIdentityRequest—contains the NotificationInfo plus identity information so that the Identity Manager can find the device information.

• EnsLib.PushNotifications.IdentityManager.NotificationByIdentityResponse—contains the response from 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:

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:

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.

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.