APNs Connector

The Apple Push Notification service connector allows you to send push notifications to iOS devices using Apple Push Notification service (APNs). APNs is a robust and highly effective service to deliver notifications to iOS and OS X devices. Fig. 1 illustrates the components that participate in sending a notification to a device.

Fig. 1

The APNs connector plays the role of the 'provider' in the above illustration. APNs providers and devices use TCP connections to connect to the APNs. The connector implementation uses java-apns V 0.2.3 as the provider library. You can download the APNs connector from https://store.wso2.com/store/assets/esbconnector/details/70e8ee70-f002-4d8b-9120-70938481232c.

The following sections describe how to send a notification using the APNs connnector. For general information on using connectors and their operations in your ESB configurations, see Using a Connector.

Configuring the connection

Use the <apns.init> element to configure the connection between the provider and APNs. The configuration has two parts: destination and connection trust.

Destination

APNs provides two destinations to connect to providers. The production destination is used when the relevant iOS apps are running in production mode. The sandbox destination is used when the relevant apps are running in development mode.

Use the <destination> element to configure the destination. The allowed option values are sandbox and production. See the samples for more details.

Connection trust

Before starting communication, the provider and APNs should establish trust between each other. This is done through a connection with TSL peer-to-peer authentication. Once the TSL connection is established, APNs sends its certificate to the provider, and then the provider should send its certificate to APNs. (This certificate is issued by Apple Inc.) Therefore, the connector should be configured with the provider certificate.  

The two components of certificate configuration are the certificate file exported as a PKSC12 file (.p12 file) and the relevant password.

The connector can look up the .p12 file in two ways. The <certificateFetchMethod> element tells the connector which method to use (see the samples for more details):

•  As a SOAP attachment: set the <certificateFetchMethod> element value to attachment, and set the <certificateAttachmentName> element value to the name of the attachment in the SOAP message.
•  As an ESB registry resource: set the  <certificateFetchMethod> element value to registry, and set the <certificateRegistryPath> element value to the path of the registry resource, e.g.,  gov:/repository/apns/certificate.p12

Properties

• destination: (Required) Destination of APNs. Valid options are sandbox and production. 
• certificateFetchMethod: (Required) The method of retrieving the provider certificate. Valid options are attachment and registry. 
• certificateRegistryPath: Path of the registry resource of the certificate if the certificate is provided as a registry resource. This element is required if certificateFetchMethod is set to the value registry.
• certificateAttachmentName: Name of the certificate attachment in the SOAP message. This element is required if certificateFetchMethod is set to the value attachment.
• password: (Required) Password of the certificate file.

Samples

<apns.init>
	<destination>sandbox</destination>
    <certificateFetchMethod>registry</certificateFetchMethod>
    <certificateRegistryPath>gov:/repository/apns/certificate.p12</certificateRegistryPath>
    <password>{wso2:vault-lookup('apns.certificate1.password')}</password>
</apns.init>

<apns.init>
	<destination>sandbox</destination>
    <certificateFetchMethod>attachment</certificateFetchMethod>
    <certificateAttachmentName>my_certificate</certificateAttachmentName>
    <password>{wso2:vault-lookup('apns.certificate1.password')}</password>
</apns.init>

Entering secure data

For security purposes, you should store your SID and token in the WSO2 secure vault and reference it by alias instead of hard-coding the actual values in the configuration file. For more information, see Working with Passwords.

Re-using APNs connection configurations

For best results, save the connection configuration as a local entry. You can then easily reference it with the configKey attribute in your APNs operations. For example, if you saved the above <apns.init> entry as a local entry named MyAPNsConfig, you could reference it from the dispatchToDevice operation as follows:

<apns.dispatchToDevice configKey="MyAPNsConfig" />

Sending push notifications

<apns.dispatchToDevice configKey="MyAPNsConfig">
	<deviceToken>0D5AD86BF2F39146ACEC09F06621EB0FB2636EF57CBFB3D6E30B69DDCD37D944</deviceToken>
    <alert>Hello iOS</alert>
    <sound>default</sound>
    <badge>1</badge>
</apns.dispatchToDevice>

To send a notification to a device, use the apns.dispatchToDevice operation and specify the following properties. APNs doesn't send any response back unless something goes wrong, and there is no way that a provider can find out whether a specific push notification got delivered to a specific device. Therefore, the apns.dispatchToDevice operation only sends true as the response unless something went wrong. In case of error conditions, error codes will be returned.    

Properties

• deviceToken: (Required) Token of the device to which the notification should be sent.
• alert: Alert message of the notification payload.
• sound: Name of the sound clip to be played when the notification is received by the device. 
• badge: Badge value of the notification payload.

When the properties alert and sound are not present, they will not be included in the payload. But when the property badge is not present, the value 0 will be added to the payload. Therefore, even if all payload properties are missing, a payload with badge value 0 will be sent to the device.

Related APNs documentation

APNs Documentation

Error codes

The following table describes the error codes returned by the APNs connector.

Example

The following code blocks show a local registry entry, a sample proxy service that uses the APNs connector, a SOAP request for the proxy service, and the response SOAP message.

<apns.init>
	<destination>sandbox</destination>
    <certificateFetchMethod>registry</certificateFetchMethod>
    <certificateRegistryPath>gov:/repository/apns/certificate.p12</certificateRegistryPath>
    <password>{wso2:vault-lookup('apns.certificate1.password')}</password>
</apns.init>

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="apns_push"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
       <inSequence xmlns:apns="urn:org.wso2.carbon.connector.apns">
          <property name="deviceToken"
                     expression="//apns:deviceToken/text()"/>
           <property name="alert"
                     expression="//apns:alert/text()"/>
           <property name="sound"
                     expression="//apns:sound/text()"/>
           <property name="badge"
                     expression="//apns:badge/text()"/>
           <apns.dispatchToDevice configKey="MyAPNsConfig">
               <deviceToken>{$ctx:deviceToken}</deviceToken>
               <alert>{$ctx:alert}</alert>
               <sound>{$ctx:sound}</sound>
               <badge>{$ctx:badge}</badge>
           </apns.dispatchToDevice>
           <respond/>
       </inSequence>
       <outSequence>
           <log />
           <send />
       </outSequence>
       <faultSequence>
           <makefault version="soap11">
               <code expression="get-property('ERROR_CODE')" />
               <reason expression="get-property('ERROR_MESSAGE')" />
               <detail />
           </makefault>
           <send />
       </faultSequence>
   </target>
   <description/>
</proxy>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:To>http://localhost:9000/soap/NoService</wsa:To>
    <wsa:MessageID>apns:uuid:e14b229d-1a68-4855-a86d-93c09b72b964</wsa:MessageID>
    <wsa:Action>apns:pushMessage</wsa:Action>
  </soapenv:Header>
  <soapenv:Body >
    <apns:pushMessage xmlns:apns="urn:org.wso2.carbon.connector.apns">
      <apns:message>
        <apns:deviceToken>0D5AD86BF2F79146ACEC09F066213B0FB2636EF57CBFB3D6E30B69D8CD37D944</apns:deviceToken>
        <apns:alert>Test Message - Final</apns:alert>
        <apns:badge>0</apns:badge>
        <apns:sound>default</apns:sound>
      </apns:message>
    </apns:pushMessage>
  </soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <apns:dispatchToDeviceResult xmlns:apns="urn:org.wso2.carbon.connector.apns">
         <apns:successful>true</apns:successful>
      </apns:dispatchToDeviceResult>
   </soapenv:Body>
</soapenv:Envelope>