Communicating with MI Service

The MI Service publishes certain service end points to the mobile client applications (iOS and Android) for consumption during the communication process.

The following end points are RESTful web services:

  • Device Registration Service Interface: to register the device for receiving the notifications.
  • Device Deregistration Service Interface: to deregister the device to stop receiving notifications from the Mobile Integration service.
  • Acknowledgment Service Interface: to accept acknowledgments sent by the device after receiving the notifications.
  • Pending Notifications Service Interface: to serve the pending notifications to the device.

Payload Keys

The following table lists the payload keys and what they denote.

Payload Keys Definition
nid Notification ID
bid Signifies the Business ID specified for correlating the business process and notifications.
faf FireAndForget flag indicates whether to manage or not to manage the notifications.
badge Signifies the number of waiting notifications on the MI service. It is dynamically stamped in case of managed notifications, and as per the user specification for the notifications that are not managed.
ns Signifies the notifications containing an array of the list of specified properties.

Device Registration Service Interface

Here you get familiar with Device Registrations Service Interface for the iOS and Android applications.

For iOS Mobile Application

Whenever the mobile application is installed or launched, it communicates with APNS to obtain its device token. The mobile application calls this BWMI service to communicate back the device token (deviceId) it has received from APNS:

  • For a new device token
  • When the device token has changed
  • When the user turns on the notification through the IOS notification store configuration

Refer to the following REST/JSON data to communicate back to the MI service: 

URI : http://<serverHost>:<serverPort>/devices
Method: PUT
Request Headers: Content-Type: application/json; charset=UTF-8
Request Body:
{
"deviceId":"d7a9876f73f84725914a11a25b89c3769f213d453b62ec7d38d241
b2fc10a8445",
       "type":"IOS",
       "user": {
               "phone": "+19883999901",
               "email": "abc@yahoo.com"
       }
}
Response Code:201 Created
Response body: None

For Android Mobile Application

Whenever the mobile application is installed or launched, it communicates with GCM server to obtain its Registration ID (deviceId). The mobile application then calls this MI service to communicate back the Registration ID it has received from the GCM Server in the following cases:

  • For a new registration id
  • When the registration id has changed
  • When the user turns on the notification through the Android notification store configuration

Refer to the following REST/JSON data to communicate back to the BWMI service: 

URI : http://<serverHost>:<serverPort>/devices
Method: PUT
Request Headers: Content-Type: application/json; charset=UTF-8
Request Body:
{

"deviceId":"GPA91bEthw8OzOYyDykm1Lvvcd3gP7oe52C9fiYobOVPems10fGmgQ
pkTpJIht9UplhsygL2zUwa2B5YjpsP3MexPb6hmv-2E9AkJKQyeBCrLvSvJL_FBser
PXskrx4LhVQeHZu3_maSIW6GkFVPtwNIzfxY-GfsIA",
         "type":"ANDROID",
         "user": {
                 "phone": "+19883999901",
                 "email": "abc@yahoo.com"
           }
}
Response Code:201 Created
Response body: None

Device Deregistration Service Interface

The mobile application calls this BWMI Deregistration service to communicate the inactive or invalid status of the mobile application whenever:

  • The user turns off the notification through the IOS notification store configuration.
  • The user turns off the device or uninstalls the application.

As a result of this deregistration service, the MI service ensures that no further notification is sent to this mobile application unless it receives a registration.

The following REST/JSON data is required to communicate back to the MI service.

For Mobile Client Application 

Un-register Device
URI : http://<serverHost>:<serverPort>/devices
Method: DELETE
Request Headers: Content-Type: application/json; charset=UTF-8
Request Body:
{

          "deviceId":"d7a9876f73f84725914a11a25b89c3769f213d453b62ec
7d38d241b2fc10a8445",
          "type":"IOS|ANDROID",
          "user": {
                  "phone": "+19883999901",
                  "email": "abc@yahoo.com"
         }
}
Response Code: 200 OK
Response body: None

Acknowledgement Service Interface

The mobile application calls the Acknowledgement Service, when the user views the managed notification in the mobile application. Use the JSON data from the managed notification to construct the acknowledgement request.

The following REST/JSON data is required to communicate back to the MI service. 

URI : http://<serverHost>:<serverPort>/acks
Method: PUT
Request Headers: Content-Type: application/json; charset=UTF-8
Request Body:
{"nid":"<notificationID>","did":"<deviceToken>","bid":"<businessID>"}
Response Code: 201 Created
Response body: None

Pending Notifications Service Interface

Whenever the mobile application is installed or launched, it communicates with APNS or GCM server to obtain its device token. The mobile application calls this MI service to communicate back the device token (deviceId) it has received from APNS or GCM server. This happens when the user:

  • Clicks on the notification in the notification store and the mobile application is launched.
  • Explicitly launches the mobile application.

The following REST/JSON data is required to communicate back to the MI service. 

URI :
http://<serverHost>:<serverPort>/devices/{deviceToken}/notifications
Method: GET
Request Headers: None
Request Body: None
Response Code: 200 OK
Response Content-type: application/json;
Response body:
{
 "ns":[
[<notification id string>,<UTC date string>,<notification alert
text>,<optional businessId string>],
[<notification id string>,<UTC date string>,<notification alert
text>,<optional businessId string>],
[<notification id string>,<UTC date string>,<notification alert
text>,<optional businessId string>]
]
}
For example,
{
 "ns":[
["b8ba7a54-92dc-4978-b125-53bfe57daa6c","1365753980483","Boarding
announced at Terminal 1, Gate B67","GATE_CHANGE"],
["fd97b8b3-4aa3-47f3-8023-606e3c548d4d","1365753981820","Flight
canceled, "FLIGHT_CANCELLATION"],
["9d5e1138-3b2e-4f88-8185-46d6e38fa21b","1365753983879","20% discount
on all Round Trip travel bookings","OFFERS"]
  ]

Push Notification Payloads

The following are the iOS and GCM payloads notifications received by the mobile applications:

  • Payloads Delivered to the iOS Application Through APNS: For iOS payloads, refer to Apple documentation for Apple Push Service.
  • Payloads Delivered to the Android Application Through GCM Server: Android application receives the following payloads from the MI Service through GCM Server.
    The application developers must handle the following payloads in their application.
    • For Managed Notification: These notifications are managed by the MI Service. 
      {
"text":"Cash withdrawal",
"timestamp":"1374224245011",
"nid":"0a1868e6-04c9-4d3b-8125-2f9597f68e78",
"bid":"USER_TRANSACTION",
"faf":"false",
"badge":"1"
}
    • For UnManaged Notification: These notifications are not managed by the BWMI service. 
      {
"text":"Salary deposited",
"faf":"true",
"sound":"default",
"badge":"1"
}
    • For Badge Update: If there is no live notification on the server, then it sends this badge value as 0. 
      {
"badge":"1"
}
    • For Pulled String of Notifications 
      {
"ns":[
["642d1380-6b98-4108-ba97-98e54483d8b9","1375952245016","Alert
2:27:25 PM"],
["78241424-0736-4301-b45f-920bd8ad84ed","1375952255016","Alert
2:27:35 PM"],
["0187a77f-b757-4b84-8768-c1ac2ddad133","1375952265015","Alert
2:27:45 PM"],
["7f015ae7-423b-4dd6-9bd2-3198d7fe534f","1375952275008","Alert
2:27:55 PM"]
]
}