Mobilet Protocol
Mobilet protocol is JSON based “Communication Bridge" between native and java script. Mobilet has standard format for all services offered by the native containers. JSON offer following advantages as a communication protocol for Native-JavaScript bridge:
- Lightweight –JSON being lightweight XML will enhance performance and reduce communication latencies
- Standard – Since, all the native containers (Android, iOS and WP) as well as JavaScript have built in support for JSON fabrication as well as parsing, thus communication will be relative
Mobilet JSON has been structured in request, response and generic categories.
Generic Parameters
Here are the list of generic parameters on Mobilet protocol:
| Parameter name | Purpose(Description) | Value set |
|---|---|---|
| transactionId | A unique ID that uniquely identifies the request-response pair. | Timestamp at the time of initiation of the request at the web layer. Thus will be a numeric value |
| isResponseExpected | A flag that indicates that whether or not a response/ callback is expected as a completion of this operation. Applicable for all types of events such as Web, Co and App event. Events such as App events do not provide a response/ callback whereas Web and Co events provide response/ callback. | Boolean value true or false. |
| transactionRequest | JSON object containing the service specific request parameters as specified above | JSON object |
| transactionResponse | JSON object containing the service specific response parameters as specified above | JSON object |
Parameters Contained on Request
Here are the list of parameters contained on request object:
| Parameter name | Purpose(Description) | Value set |
|---|---|---|
| eventType | Numeric value indicating the type of event. Could be any of Web, Co or App events. | 1/2/3 for Web, Co and App events respectively |
| serviceId | Indicates the type of service being selected by the user. Could be any of services offered by the framework like UI, HTTP, Database, Maps etc. | Numeric values ranging from 01-99 |
| serviceSubType | Denotes the specific operation within the selected service that needs to be performed. Like reading/ saving / deleting records are all operations in Database service | Numeric values ranging from 01-99 |
| serviceRequestData | Base64 encoded request string. Will be the same data as was returned by the data callback function of the service when called from the native container | String message containing Base64 encoded request message |
Parameters Contained on serviceRequestData
The Base 64 decoded serviceRequestData would have the JSON structure that would vary in accordance with the type of service as follows:
| Service type | serviceRequestDataFormat | Parameter Description |
|---|---|---|
| UI service | {‘message’:’<JSON object/array containing service request data. Will be a JSON array in cases such as multi-item list selection components>’} | |
| HTTP service | {‘requestMethod’:’GET/POST/PUT/DELETE’,‘requestUrl’:’<HTTP-REQUEST-URL>’,’requestHeaderInfo’:[<JSON-ARRAY-HEADERS>], ‘requestPostBody’:’<POST-BODY>’,’requestContentType’:’<CONTENT-TYPE>’,’requestFileInformation’:[<FILES(S) INFO TO BE UPLOADED>]} | |
| Persistence service | {‘storeName’:’<Name of appn persistence store>’,’requestData’:’<JSON array containing keys for retrieve/delete operations or key-value pairs for save operations>’} | |
| Database service | {‘appDB’:’<Name of application database>’,’queryRequest’:’<Query to be executed>’} | |
| Co event service | NEED TO DISCUSS THE RELEVANCE OF THIS SERVICE | |
| App Event service | NEED TO DISCUSS THE RELEVANCE OF THIS SERVICE | |
| Map service | {‘locations’:[{ ‘locLatitude’:’<latitude>’, ‘locLongitude’:’<longitude>’, ‘locMarkerPin’:’<color code of marker pin>’, ‘locTitle’:’<title of the location>’, ‘locDescription’:’<description of marked location>’},…legends:[<MAP-LEGENDS-THAT-NEED-TO-BE-MARKED-ON-MAP >]]} | |
| File service | {‘fileName’:’<Name including the location of the file to be read>’} | |
| Camera service | {‘cameraDirection’:’<Front/Rear camera to use>’,‘compressionLevel’:’<1-100 compression ratio>’,‘imageEncoding’:’JPG/PNG’,‘imageReturnType’:’URL/Base64’,‘imageFilter’:’STANDARD,SEPIA etc.’,‘imageSource’:’Camera/Gallery’} |
Parameters Contained on Response
Here are the list of parameters contained on response object:
| Parameter name | Purpose(Description) | Value set |
|---|---|---|
| isOperationComplete | Flag that indicates whether or not the | Boolean value true or false. |
| serviceResponse | Base64 encoded string containing response of the service invoked. Purpose of Base64 encoding this parameter is to avoid special characters affecting the communication | Base 64 encoded string containing service completion response |
| exceptionType | A unique code denoting the type of exception encountered at the native end in completion of the service request | |
| exceptionMessage | Accompanying string message describing the nature of problem in service request completion |
Parameters Contained on serviceResponse
The Base64 decoded serviceResponse would have the JSON structure specified by the following:
| Service type | serviceResponseFormat | Parameter Description |
|---|---|---|
| UI service | {‘userSelection’:’<Value of selection of the user>’} | Value of ‘userSelection’ depends on the type of operation. For progress dialog the value returned would be ‘null’. For Decision dialog or alert dialog, it would provide the selection like ‘OK’,’Yes’,’No’. For multiple selection, it would return the index/indices of the user selection |
| HTTP service | {‘httpResponseHeaders’:[<JSON array containing list of headers received in response>], ‘httpResponse’ : ‘<HTTP response>’} | |
| Persistence service | {‘storeName’:‘<Name of persistence store>’,’storeReturnData’:[]} | The parameter ‘returnData’ would contain a value only in case of READ operation from the Persistence service. For SAVE and DELETE operations, the flag ‘isOperationComplete’ in the root of the response object would indicate the completion of the operation |
| Database service | {‘appDB’:’<Name of the DB being accessed>’,’dbRecords’:[<JSON array containing >]} | The parameter ‘dbRecords’ would contain value only in case of DB READ operation. In other DB operations, the flag ‘isOperationComplete’ in the root of the response object would indicate the completion of the operation |
| Co event service | NEED TO DISCUSS THE RELEVANCE OF THIS SERVICE | |
| App Event service | NEED TO DISCUSS THE RELEVANCE OF THIS SERVICE | |
| Map service | NO RESPONSE REQUIRED- As the user will receive a callback only after coming back to the web view from the maps, so this would indicate that the map has been shown. Moreover, the flag ‘isOperationComplete’ in the root of the response object would indicate the completion of the operation | |
| File service | {‘fileContents’: [{‘fileName’:’<Name of the file. Should be same as specified by the user>’,’fileContent’:’<Base64 encoded string containing file information>’,’fileType’:<Should indicate the type of file>’,’fileSize’:’<Size of file in bytes>’},…]} | Here more information regarding the file being read can be provided to the user. |
| Camera service | {‘imageURL’:’<Location where image saved>’,‘imageData’:’<Base64 image data>’,‘imageType’:’<image format>’} | Properties ‘imageURL’, ‘imageData’ are mutually exclusive i.e. at a time only one of them will contain data |
JSON Structure
Consolidated JSON of Mobilet communication protocol would look like as:
{
"transactionId":"<Unique-ID denoted by timestamp>",
"isResponseExpected":"<Boolean value on whether or not response expected>",
"transactionRequest":{
"serviceOperationId":"<Unique ID for service operation>",
"serviceRequestData":"<JSON object for service specific request data>"
},
"transactionResponse":{
"isOperationComplete":"<indicates whether or not the operation complete>",
"serviceResponse":"<JSON object for service operation response data>",
"exceptionType":"<Negative integer code representing the type of exception>",
"exceptionMessage":"<Detail regarding exception occured>"
}
}