This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
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 toattachment
, 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 toregistry
, 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 aresandbox
andproduction
.certificateFetchMethod
: (Required) The method of retrieving the provider certificate. Valid options areattachment
andregistry
.certificateRegistryPath
: Path of the registry resource of the certificate if the certificate is provided as a registry resource. This element is required ifcertificateFetchMethod
is set to the valueregistry
.certificateAttachmentName
: Name of the certificate attachment in the SOAP message. This element is required ifcertificateFetchMethod
is set to the valueattachment
.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
Error codes
The following table describes the error codes returned by the APNs connector.
Error Code | Description |
---|---|
APNS_000001 | Required parameters are missing or not valid. |
APNS_000002 | The certificate file cannot be found, read, or decrypted, or Apple rejected the certificate. |
APNS_000003 | The given APNs destination is not 'production' or 'sandbox'. |
APNS_000004 | An APNs service error occurred. |
APNS_000005 | The SOAP response cannot be built. |
APNS_000006 | The payload is not acceptable by APNs (e.g, payload is too long). |
APNS_000007 | Errors that are not covered by the above codes. |
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>