Push Notification Alerts Guide – Tech Mahindra’s Arrayent ConnectCloud IoT Platform Developers Portal

Overview

This guide explains the workflow for implementing mobile push notification alerts. This guide applies to iOS and Android push notifications. The overall workflow is the same for iOS and Android, with some minor variations in implementation, which we will note where appropriate.

Scope and Audience

Topics that do not explicitly involve Arrayent, such as how to generate security certificates from Apple or Google, are not covered in this guide. We have attempted to provide help as much as possible, but it is your responsibility to make sure that you are following best practices in relation to these topics. You should have some experience with implementing push notifications in iOS or Android apps before using this guide.

Push Notifications Overview

Push Notification Alerts function like all other alerts in the Arrayent Connect Platform: you define the event that triggers the alert and the action to take when the alert is triggered (in this case, sending out a push notification to an Android or iOS device). The Arrayent Alert Engine monitors the status of the device and pushes out the notification to the mobile device whenever the alert is triggered. Arrayent does not actually deliver the push notification directly to the target mobile devices. For security and complexity reasons, Google and Apple provide notification services for delivering push notifications to their respective smartphones. The Google service is called the Google Cloud Messaging Service (GCMS), and the Apple service is called the Apple Push Notification Service (APNS). When a Push Notification Alert is triggered, the Arrayent Alert Engine sends the notification to one of these two services. The message that the Arrayent Cloud sends to the notification service includes address information for the target device and the target application, authentication credentials which verifies that the Arrayent Cloud has permission to send push notifications, and of course the message contents that the end user will see. Before routing any notifications to devices, the notification services make sure that the originator of the push notification (the Arrayent Cloud) is actually authorized to send push notifications to the device and the app. Once the notification services have authenticated the cloud, the services then route the notification to the mobile device.

Push Notification Implementation General Workflow

The general workflow for enabling push notification alerts contains three major steps: uploading certificates, registering mobile devices with the Arrayent Cloud via your app, and implementing the push notification alerts via your app.

Uploading security certificates. When the Arrayent Cloud delivers notification packages to the Google and Apple notification services, the cloud provides these certificates to the notification services to prove that it is authorized to send messages to mobile devices on behalf of your app. This is typically a one-off procedure that you complete manually using the Arrayent Configurator app.
Registering mobile devices with the Arrayent Cloud. Apple and Google both have their own unique requirements for identifying their mobile devices. The Arrayent Cloud cannot send push notifications without this device identifier information. So you need to modify your app to retrieve this information from the device and send the device identifier information to the Arrayent Cloud. This behavior is programmed into the business logic of your app. Your app sends this information to the Arrayent Cloud using the Arrayent Web Service API.
Define the push notification alert. This behavior is programmed into the business logic of your app. Your app defines the alert using the Arrayent Web Service API.

The remainder of this guide dives into the implementation details of the three general steps described above.

Terminology

This guide uses the following terms.

Name	Description
Android Device	An Android smartphone or tablet. When we use this term, we are implying that the matter at hand only applies to Android devices, and not iOS devices.
End Users	The people who have installed your app onto their mobile devices. The recipient of the push notification.
iOS Devices	An iOS smartphone or tablet. When we use this term, we are implying that the matter at hand only applies to iOS devices, and not Android devices.
Mobile Device	An Android or iOS smartphone or tablet. When we use the term mobile device, we are implying that the matter at hand applies to both Android and iOS devices.
Mobile Device ID	A permanent, unique ID of the mobile device, such as a MAC address. This is referenced as `nativeId` in the Arrayent Web Service API.
Mobile Device Record	The Arrayent Cloud’s database record of identifier information for an individual mobile device. This information is uploaded to the Arrayent Cloud from your mobile device app. We use the term ‘record’ to emphasize that the Arrayent Cloud is passively storing the information that it receives from your app.
Mobile Device Security Token	The security token that the Arrayent Cloud sends to the notification service to identify an individual mobile device. After the end user grants permission to your app to use push notifications, the notification service generates the mobile device security token and delivers the token to the mobile device. Your app requests this token from the mobile device, and then sends it to the Arrayent Cloud. This is called the`nativeSecurityToken` in the Arrayent Web Service API.
Notification Service	The cloud service provided by the mobile device OS manufacturer which handles the actual delivery of push notifications to mobile devices. For Android devices, this is the Google Cloud Message Service. For iOS devices, this is the Apple Push Notification Service. When the Arrayent Cloud sends push notifications, it is actually sending the message to one of these two notifcation services. The notification service delivers the push notification to the actual mobile device.
Phone ID	A random integer that the Arrayent Cloud generates after a mobile device record is successfully created. When updating a mobile device record or defining a push notification alert, you reference the mobile device by its Phone ID. This is called the`phoneId` in the Arrayent Web Service API.

Uploading Security Certificates via the Arrayent Configurator

This section explains how to upload security certificates to the Arrayent Cloud, so that the Arrayent Cloud can send push notifications on behalf of your app. You will need access to the Arrayent Configurator app to complete this section. We assume that you have basic familiarity with the Configurator. The Configurator Reference can provide more information on how to use the app if needed.

Generating Security Certificates

There are a lot of tutorials online which describe the process for generating push notification security certificates for iOS and Android apps. The following links are a starting point, but it’s your responsibility to ensure that you are following up-to-date and best practices. http://www.raywenderlich.com/32960/apple-push-notification-services-in-ios-6-tutorial-part-1 http://developer.android.com/google/gcm/gs.html

Uploading Security Certificates for Enabling iOS Push Notifications

See Uploading iOS Certificates.

Uploading Security Certificates for Enabling Android Push Notifications

See Uploading Android Certificates.

Managing Mobile Device Records

To review, when the Arrayent Cloud sends a push notification to an Android or iOS device, it is actually sending the notification to the Google Cloud Messaging Service or Apple Push Notification Service. These notification services take care of delivering the notification to the physical device. Both the Google and Apple notification services implement opaque schemes for identifying mobile devices. They both require that your application asks the end user for permission to send push notifications. If the end user opts in to the service, then (and only then) will your app be able to retrieve a unique identifier for the device. Once your app receives that unique secuirty token, your app needs to upload that token to the Arrayent Cloud. In this guide we call this the “mobile device security token”. This scheme is designed to ensure that only authenticated backends are able to send notifications to mobile devices (without the app sending the identifier to the backend host, the backend host would never be able to guess the identifier of a device). Whenever the Arrayent Cloud sends a push notification, it uses this idenfitifer to identify the exact target device of the push notification. Your application is responsible for uploading this mobile device security token to the Arrayent Cloud, and ensuring that the Arrayent Cloud’s record for the device remains up to date. Without the token, the cloud won’t be able to send push notifications to individual mobile devices. These tasks are accomplished with the Arrayent Web Service API. The most common tasks that your app will perform related to mobile devices are creating, reading, updating, and deleting (CRUD) the Arrayent Cloud’s mobile device identifier records.

Creating Mobile Device Records

This section describes the context and implementation of the initial registration of mobile devices in the Arrayent Cloud. After the end user first installs your app and opts in to the push notification service, you need to register the mobile device with the Arrayent Cloud, so that the cloud has the device identifier information that it needs to send push notifications to the mobile device. By “register the device” we mean that your app sends the Arrayent Cloud device identifier information, and the Arrayent Cloud records this information in a database record. We call the information stored in the Arrayent Cloud the “mobile device record”.

Implementation

Register a mobile device to receive push notifications with the registerMobilePhone web service operation. Upon successful registration, the Arrayent Cloud will generate a random ID for the mobile device, called the phoneId. Your app will need to reference the mobile device by its phoneId whenever it wants to perform subsequent operations on the mobile device, such as defining the alert that triggers the push notification.

https://example.arrayent.com:8081/zdk/services/zamapi/registerMobilePhone?
secToken=123-1234567890&userId=12345&nativeId=123456789ABCDEF123&
operatingSystem=ios&nativeSecurityToken=1234567890abcdef1234567890abcd

<ns1:registerMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
 <phoneId>123</phoneId>
</ns1:registerMobilePhoneResponse>

Retrieving Mobile Device Records

The most common use case for retrieving a mobile device record is creating a new push notification alert. When you create the alert, you need to reference the mobile device by its Phone ID (phoneId). The best practice is to programmatically retrieve this information using the Arrayent Web Service API.

Note

In the past, we instructed web service developers to write mobile device information such as phoneId to disk. In the short term, this practice won’t cause any problems, but the best practice is to programmatically retrieve the information whenever you need it.

Implementation

Use getMobilePhonesByUserId to retrieve a mobile device record from the Arrayent Cloud. If the end user has registered multiple devices to receive push notifications, then getMobilePhonesByUserId will contain the records of all of these mobile devices. Therefore, you will need to search for the mobile device among the list of results returned by the Arrayent Cloud. Retrieve the mobile device ID from the device OS (this is the value which you provided for nativeId when you initially registered the device via registerMobilePhone). Use this value to locate your device from the list of records included in the result ofgetMobilePhonesByUserId.

getMobilePhonesByUserId Example

The request below returns a list of all mobile devices that a particular user has registered to receive push notifications. The User ID of the user can be retrieved via the web service operation getUserValueList.

https://example.arrayent.com:8081/zdk/services/zamapi/getMobilePhonesByUserId?
secToken=123-1009933734&userId=123

getMobilePhonesByUserId returns the list of all registered mobile devices for this user. To search for a specific device, find the listing that contains your mobile device’s nativeId, which is the permanent identifier for the device which you provided as a parameter to registerMobilePhone. In this example, the nativeId is the MAC address of the mobile device.

<ns1:getMobilePhonesByUserIdResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <phoneList>
 <ID>461</ID>
 <userID>918</userID>
 <nativeID>91F9AC1367C9</nativeID>
 <nativeSecurityToken>1234567890abcdef1234567890abcdef1234567890abcdef</nativeSecurityToken>
 <operatingSystem>ANDROID</operatingSystem>
 <friendlyName>ANDROID_21:17</friendlyName>
 </phoneList>
 <phoneList>
 <ID>298</ID>
 <userID>918</userID>
 <nativeID>AB12CD34BB93</nativeID>
 <nativeSecurityToken>0987654321fedcab0987654321fedcab0987654321fedcab</nativeSecurityToken>
 <operatingSystem>IOS</operatingSystem>
 <friendlyName>IOS_18:16</friendlyName>
 </phoneList>
</ns1:getMobilePhonesByUserIdResponse>

Updating Mobile Device Records

Although unlikely, it is possible for the Arrayent Cloud’s record for a mobile device to become out of date. Therefore, it is a best practice to program your app to periodically check that the Arrayent Cloud’s record for the device is still accurate, and to update the Arrayent Cloud’s record if it is not. This section explains how the Arrayent Cloud’s record can potentially become outdated. To review, recall that the Arrayent Cloud executes push notifications by sending the push notification message to the notification services provided by Google (Google Cloud Messaging Service) and Apple (Apple Push Notification Service). The notification service takes care of actually delivering the message to the mobile device. The device identifier which the Arrayent Cloud provides to the notification service is actually a security token that is generated by the notification service and distributed to the mobile device. Your app retrieves this security token from the mobile device OS, and then sends the token to the Arrayent Cloud. The key point here is that the notification service ultimately controls the device token, and has the power to change a device’s security token. In practice, this does not appear to happen too often, but it is possible.

Warning

By design of the notification services, the Arrayent Cloud has absolutely no way of checking that its record for a mobile device is out of date, or communicating this information to your app. It is the complete responsibility of your app to make sure that the Arrayent Cloud’s record is up to date.

Implementation

Retrieve the mobile device record from the Arrayent Cloud using getMobilePhonesByUserId. See the section above on retrieving mobile device records if your user has registered multiple mobile devices and you need to search this list.
Retrieve the current mobile device security token from the device’s OS.
Compare the Arrayent Cloud’s record for the security token against the value you just retrieved from the OS. If the values are the same, then the Arrayent Cloud’s record is up to date and no action is needed. If the values are different, then the Arrayent Cloud needs to be updated.
If needed, update the Arrayent Cloud’s mobile device record with updateMobilePhone.

https://example.arrayent.com:8081/zdk/services/zamapi/updateMobilePhone?
secToken=818-230199725&userId=818&phoneId=461&nativeSecurityToken=
10amld95mx96malx94mg&friendlyName=android

<ns1:updateMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:updateMobilePhoneResponse>

Deleting Mobile Device Records

In the rare event that you need to completely delete a mobile device record, this section explains how to do so. To be clear, this is a different use case than disabling push notifications. If an end user no longer wishes to receive push notifications, you do not necessarily need to delete the Arrayent Cloud’s record for the mobile device. You just need to delete or disable the alert that is triggering the push notification. Alerts are deleted with the web service operation removeTrigger. Deleting a mobile device record implies that your web app will never send a push notification to this mobile device again.

Implementation

Use unregisterMobilePhone to delete the target mobile device record from the Arrayent Cloud. To review, the phoneId that is being used to reference the mobile device is a random integer generated by the Arrayent Cloud upon registration of the mobile device. The phoneId can be retrieved via getMobilePhonesByUserId, and searching for the mobile device record that matches your mobile device ID (the value that you provided for nativeId when you called registerMobilePhone).

https://example.arrayent.com:8081/zdk/services/zamapi/unregisterMobilePhone?
secToken=818-230199725&userId=818&phoneId=461

A return code of 0 means that the operation was successful.

<ns1:unregisterMobilePhoneResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:unregisterMobilePhoneResponse>

Managing Push Notification Alerts

The final step in enabling push notifications in your connected product mobile app is to define the alert that triggers the push notification. In this chapter we will just cover the aspects of defining alerts that are related to push notifications. We won’t cover the alert management lifecycle in its entirety.

Creating Push Notification Alerts

The first time an alert is enabled, either by the end user or by some other mechanism, your app needs to create the alert on the Arrayent Cloud. Essentially, your app is giving the Arrayent Cloud a set of instructions. It is instructing the cloud to monitor the device for a specific event, and to execute a specific action when that event occurs.

Implementation

Alerts are created with the addTrigger web service operation. Most of the parameters that you provide when calling addTrigger are related to defining the event which triggers the device. For now we’re just focusing on how to implement push notification alerts, so we won’t go into detail about the fields related to the event that triggers the alert. There are three parameters which are relevant to defining an alert as a push notification alert.

The action parameter determines the action that the cloud should take when the event is triggered. action must be set to the value mobile_notification.
address determines the recipient of the push notification.To send the alert to all mobile devices registered to this user, leave the address parameter blank. To selectively send the alert to a subset of the user’s devices, set the address parameter to a comma-separated list ofphoneId``s. Phone IDs can be retrieved with ``getMobilePhonesByUserId.
The msg parameter determines the message that is delivered to the end user. This should be set to whatever is contextually appropriate for your particular device event.

addTrigger Example (Multi-Device Push Notification)

The following request creates a push notification alert that is triggered when the online attribute of the device changes to a value less than 1 (in other words, the alert is triggered when the device goes offline). The alert definition specifies that a push notification containing the message “ALERT” should be sent to three mobile devices, identified by phoneId``s ``123, 124, and 129. Recall that these phoneId``s are generated in response to ``registerMobilePhone and can be retrieved withgetMobilePhonesByUserId.

https://example.arrayent.com:8081/zdk/services/zamapi/addTrigger?
secToken=123-1234567890&devId=12345&attrName=online&operation=
%3C&threshold=1&action=mobile_notification&address=123,124,129&
msg=ALERT&autoDisarm=1&autoDelete=0&autoDisable=0&enable=1

Leaving the address empty instructs the cloud to send the push notification to all registered mobile devices. If you register a new mobile device after creating the alert, the cloud will automatically send the alert to that device.

https://example.arrayent.com:8081/zdk/services/zamapi/addTrigger?
secToken=123-1234567890&devId=12345&attrName=online&operation=
%3C&threshold=1&action=mobile_notification&address=&msg=ALERT&
autoDisarm=1&autoDelete=0&autoDisable=0&enable=1

The fact that the Arrayent Cloud generated a Trigger ID in response to the request indicates that the alert was created successfully.

<ns1:addTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <triggerId>1111</triggerId>
</ns1:addTriggerResponse>

Retrieving Push Notification Alerts

There are two ways to retrieve alerts. You can retrieve them per device with getTriggerDetailListByDevice. This returns all of the alerts that have been defined for a particular device. You can also retrieve alerts per user with getTriggerDetailListByUser. This returns all of the alerts for all of the devices of a single user. getTriggerDetailListByDevice is obviously a subset ofgetTriggerDetailListByUser. These operations will return the full definition of each alert. You can identify which alerts are push notification alerts by checking the value of action, which will be set to mobile_notification.

https://example.arrayent.com:8081/zdk/services/zamapi/
getTriggerDetailListByDevice?secToken=123-12345678990&devId=12345

The response of getTriggerDetailListByDevice indicates that there are three alerts defined for the device, two mobile push notifications and an SMS notification.

<ns1:getTriggerDetailListByDeviceResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <trigList>
 <triggerId>1111</triggerId>
 <devId>12345</devId>
 <action>mobile_notification</action>
 <attrName>online</attrName>
 <operation><</operation>
 <threshold>1.0</threshold>
 <address>123,124</address>
 <msg>ALERT</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
 <trigList>
 <triggerId>1112</triggerId>
 <devId>12345</devId>
 <action>mobile_notification</action>
 <attrName>online</attrName>
 <operation>></operation>
 <threshold>0.0</threshold>
 <address>123,124</address>
 <msg>ALERT</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
</ns1:getTriggerDetailListByDeviceResponse>

https://example.arrayent.com:8081/zdk/services/zamapi/getTriggerDetailListByUser?
secToken=912-1693708247&userId=912

<ns1:getTriggerDetailListByUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <trigList>
 <triggerId>4012</triggerId>
 <devId>184553180</devId>
 <action>htmlemail</action>
 <attrName>movement</attrName>
 <operation>==</operation>
 <threshold>0</threshold>
 <address>joe@dirt.com</address>
 <msg>He's dead, Jim.</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
 <trigList>
 <triggerId>3815</triggerId>
 <devId>184553213</devId>
 <action>mobile_notification</action>
 <attrName>moisture</attrName>
 <operation>==</operation>
 <threshold>1.0</threshold>
 <address>943</address>
 <msg>Moisture detected.</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>false</enable>
 </trigList>
 <trigList>
 <triggerId>3816</triggerId>
 <devId>184553236</devId>
 <action>sms</action>
 <attrName>heat</attrName>
 <operation>></operation>
 <threshold>90</threshold>
 <address>16506901254</address>
 <msg>It's really hot in here...</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
 </ns1:getTriggerDetailListByUserResponse>

Updating Push Notification Alerts

When you need to update the definition of an alert, use the web service operation updTrigger. The fields of this operation are exactly the same as the fields of addTrigger.

Sending Push Notifications to Multiple Devices

You can configure an alert to send out a push notification to multiple mobile devices. This is accomplished by setting the address field of the alert to include a comma-separated list of phoneId``s. For example, suppose you want to send a push notificationto three mobile devices, with ``phoneId``s ``112, 439, and 922. To send a push notification to each device when the alert is triggered, you set address field of the alert definition to 112,439,922. The address field of the alert definition can be set when defining a new alert using addTrigger, or by using updTrigger to update an existing alert.

addTrigger Example (Multi-Device Push Notification)

https://example.arrayent.com:8081/zdk/services/zamapi/addTrigger?
secToken=123-1234567890&devId=12345&attrName=online&operation=
%3C&threshold=1&action=mobile_notification&address=123,124,129&
msg=ALERT&autoDisarm=1&autoDelete=0&autoDisable=0&enable=1

https://example.arrayent.com:8081/zdk/services/zamapi/addTrigger?
secToken=123-1234567890&devId=12345&attrName=online&operation=
%3C&threshold=1&action=mobile_notification&address=&msg=ALERT&
autoDisarm=1&autoDelete=0&autoDisable=0&enable=1

The fact that the Arrayent Cloud generated a Trigger ID in response to the request indicates that the alert was created successfully.

<ns1:addTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <triggerId>1111</triggerId>
</ns1:addTriggerResponse>

Appendix

Mobile Device Registration Process

The flowchart below summarizes the mobile device registration process.

Creating a Push Notification Alert in the Utility App

To create a push notification alert:

On the Alerts table click Add.
From the Device Code dropdown menu select the device which the alert will apply to.
From the Alert Method dropdown menu select Mobile Notification.
From the Device Attribute dropdown menu select the device attribute which the alert will apply to. Whenever the device sends a new value for this Device Attribute to the Arrayent Cloud, the cloud will compare the current value against the threshold value (which you are about to define), using the boolean operator (which you are also about to define).
From the Operation dropdown menu select the boolean operator which you want to use to compare the Device Attribute value against the threshold value.
In the textbox next to Threshold enter the integer value which you want to compare the Device Attribute value against.
In the textbox next to Message enter the message which you want the end user to receive via push notification when the alert is triggered.
Enable/disable the checkbox next to Auto Disarm according to your requirements.
Enable/disable the checkbox next to Auto Delete according to your requirements. Enabling the checkbox means that the definition of the alert will be deleted from the Arrayent Cloud after the alert is triggered. In other words, the definition of the alert will be deleted from the Arrayent Cloud’s database. You almost always want to leave this field disabled.
Enable/disable the checkbox next to Enable according to your requirements. Enabling the checkbox means that the alert is active in the Arrayent Cloud. Disabling the alert means that the alert is inactive. If the alert were to be triggered when the alert is inactive, nothing would happen.
Enable/disable the checkbox next to Auto Disable according to your requirements. Enabling the checkbox means that after the alert is triggered the Arrayent Cloud will disable the alert, which is the same as if you disabled the Enable checkbox above. This is different from Auto Delete in that Auto Delete deletes the alert definition from the Arrayent Cloud database, whereas this just disables the state of the alert. The alert definition still exists in the Arrayent Cloud database, the Arrayent Cloud simply isn’t actively monitoring the alert.
In the Mobile Phones table select which mobile devices should receive the push notification when the alert is triggered. Enabling the checkbox next to the device indicates that the mobile device should receive the push notification. Disabling the checkbox means the mobile device will not receive the push notification when the alert is triggered.
Click Save when finished.