Apple Push Notification Service Adapter

Introduction

The Apple Push Notification Service adapter allows Neuron ESB solutions to now send messages to mobile devices running on iOS devices. Using the adapter, solutions can send notifications of events to devices that are configured to receive notifications for applications that are installed on the device. These notifications can be used to send alerts to users or trigger actions in iOS applications.

Neuron ESB and the Apple Push Notification Service adapter only provide the channel that you can use to publish messages to iOS devices. You are required to provide a way of registering devices with your solution, storing device identifiers, and mapping events to device identifiers.

Before reading this document

If you are not familiar with Neuron ESB Adapters, take a moment to consult the Adapter Overview. This document assumes you have the following knowledge:

1. What adapters are and how they are leveraged in Neuron ESB
2. Register a Neuron ESB Adapter within a Neuron ESB Solution
3. Create an Adapter Endpoint in a Neuron ESB Solution
4. Set a Neuron ESB Adapter Endpoint Properties
5. Invoke a Neuron ESB Adapter Endpoint

Supported Modes

The Apple Push Notification Service adapter the Subscribe and Publish.

Publish Mode

In Publish mode, the Apple Push Notification Service adapter acts as a publisher and will publish messages from the Apple Feedback Service to a topic. The Apple Feedback Service will alert your Neuron ESB solution about failed remote notifications. When a notification cannot be delivered to a device, the Feedback Service will add that device to its list of failed devices and will make the device identifier available to your Neuron ESB solution.

Subscribe Mode

In the Subscribe mode, the adapter will connect to the topic as a subscriber and will forward messages that it receives to the Apple Push Notification Service to be delivered to the iOS device specified in the metadata for the message.

Properties

General Properties

• Use Development Server?: if set to True, the adapter will be used with the sandboxed APNS development service. This is useful for applications under development or that are being beta tested using the TestFlight service. If set to False, the adapter will use the production APNS service.

Publish Mode Properties

• Topic: The name of the topic that the adapter will publish the device identifiers for devices that are reported to no longer receive messages from the application.
• Polling Interval: The polling interval controls how often the adapter will check for feedback from the Feedback Service. The value is the number of minutes between polling attempts.
• Error Reporting: specifies the severity level of errors that are reported by the adapter. Errors can be logged either as errors, warnings, or informational messages in the Neuron ESB event log.
• Error On Polling: Indicates how to proceed when errors occur. You can use this property to stop the adapter from polling the Feedback Service for additional notifications if an error occurs; to report the first error and ignore repeated errors; or to report all errors.

Security Properties

• Certificate Name: APNS uses SSL with client-certificate authentication. This property stores the name of an X.509 v2 certificate that has been registered in the Neuron ESB solution in the Credentials store. The client certificate will need to be deployed to the host machines certificate store for Neuron ESB to resolve the certificate at runtime.

Messages

Metadata

The Apple Push Notification Service adapter uses custom properties to attach metadata to messages that are published from the adapter or to route messages to the Apple Push Notification Service that are sent to the adapter. The custom properties are documented in the following sections. The Apple Push Notification Services uses the prefix apns for its metadata.

Publish Mode

In Publish Mode, the Apple Push Notification Service adapter connects to the Apple Feedback Service and publishes the device identifiers for devices that notifications could not be delivered to. The body of the message is a hexadecimal string representing the device identifier of the device that could not be delivered to.

The adapter sets the apns.timestamp custom property in the message header for device notifications. The timestamp value is the number of seconds since January 1, 1970 UTC, and indicates the time at which the Apple Push Notification Service determined that the device was no longer accessible to the application.

Subscribe Mode

In Subscribe Mode, the Apple Push Notification Service adapter will forward messages to the Apple Push Notification Service. The message body should contain a JSON object that describes the message to be sent to an iOS device and information on how the application should handle the notification. The format and structure of the message body is documented here: https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW1

The Apple Push Notification Service adapter uses custom properties on the message to route the message to the intended target device. The following custom properties are used on messages:

• apns.deviceToken: This is a hexstring identifier for the iOS device that should receive the notification. This string is returned to your iOS application in the AppDelegates application: didRegisterForRemoteNotificationsWithDeviceToken: method is invoked. This property is required.
• apns.notificationId: This is an sequential integer identifier that is application-specific. Your solution can use this identifier to match error responses to notifications that were sent to determine devices that were unable to receive notifications. This property is required.
• apns.expires: This is a date/time string in the format yyyy-MM-dd HH:mm:ss. This property is optional. If specified, this property tells the APNS service at which point this message becomes expired and the APNS service should no longer attempt to deliver the message to the device. The time should be specified relative to UTC.
• apns.priority: This is an integer priority level. This value can be one of the following values:
  • 10: the message is sent immediately
  • 5: the message is sent at a time that conserves power on the receiving device.

The metadata can be specified on a message when published, or can be added to the message inside of a business process or workflow activity. For example, to add the properties to a message inside of a business process, you would use the following source code inside of a C# activity:

context.Data.SetProperty(apns, deviceToken, PUT-DEVICE-TOKEN-HERE);
context.Data.SetProperty(apns, notificationId, 1);
context.Data.SetProperty(apns, priority, 10);

Use Cases

The Apple Push Notification Service adapter has the following use cases:

• Send an alert to a user using an iOS application. An example alert may be the headline of a news story, an update to an order that the user placed, or some other readable message that you want to appear in the users notifications list.
• Update the badge indicator for an iOS application. This can be useful for an application involving workflow tasks, for example, to let the user know how many activities need her attention.

Sample

The source code for a sample iOS application that registers for remote notifications and can receive events from the Apple Push Notification Service adapter has been published to GitHub. You can download the source code from https://github.com/neuronesb/apns-demo.