Communicating with BWMI Server

The BW Mobile Integration server publishes the following service end points to the mobile client applications (iOS and Android) for consumption.

Each of these end points is a RESTful web service and is described in detail in the following sections:

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.

The following table lists the payload keys:

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 unmanage the notifications.
`badge`	Signifies the number of waiting notifications on the BWMI server. 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 must call 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 JSON data to communicate back to the BWMI server:

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 or FCM server to obtain its Registration ID (deviceId). The mobile application calls this BWMI server to communicate back the Registration ID it has received from the GCM or FCM 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 JSON data to communicate back to the BWMI server:

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 BWMI server ensures that no further notification is sent to this mobile application unless it receives a registration.

The following JSON data is required to communicate back to the BWMI server.

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 JSON data is required to communicate back to the BWMI server.

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 BWMI server 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 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 or FCM 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 BWMI Server through GCM Server.

The application developers must handle the following payloads in their application.

For Managed Notification: These notifications are managed by the BWMI Server.

{
"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 server.
```
{
"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"]
]
}

Payloads Delivered to the Android Application Through the FCM Server
Android application receives the following payloads from BWMI Server through FCM Server.

The application developers must handle these payloads in their application. For more information about Android payloads, see Firebase documentation.

Contents