1. Mobile Plugin Framework
  2. Camera support in Mobile Plugin Framework

Camera support in Mobile Plugin Framework

The in-app camera module provides several useful benefits to the user such as control of flashlight, zoom, autofocus adjustment, retake photo and front/back camera switch. The resulting photo can be controlled by additional parameters: quality, targetWidth and targetHeight. These provide the opportunity to control the size of the photo and it's resolution. The resulting photo that is returned by the "takePhoto" procedure is in JPEG format.

The Mobile Plugin Framework supports a new 'takePhoto' procedure that provides the ability for the user to use their device camera to get a picture into a plugin. This procedure utilizes the in-app-camera that works for 'image' properties within Oracle Field Service. This feature is designed for use within the installed iOS and Android applications. Browser support is not available.

  • The resulting photo can be controlled by additional parameters: quality, targetWidth and targetHeigh. These provide the opportunity to control the size of the photo and it's resolution.
  • The resulting photo that is returned by the "takePhoto" procedure is in JPEG format.
  • The resolution of the photo is based on a device's camera module and it is cropped according to the screen aspect ratio. So the final image aspect ratio could differ between portrait and landscape modes. Also, the final image can be cropped via functionality of the in-app camera; in this case the width or height of the photo will be cut.

How To Use

  1. Add "sendMessageAsJsObject": true item to "ready method"
  2. Open the plugin on iOS/Android device (not in browser)
  3. Check that the "takePhoto" procedure is available in the list of "allowedProcedures" in "open" method

  4. Run the "takePhoto" procedure by using the following code:


let data = {
            "apiVersion": 1,
            "method": "callProcedure",
            "callId": "123",
            "procedure": "takePhoto"
}
parent.postMessage(data, document.referrer);

Request

The request could be called with or without parameters. These parameters are all optional:

  • quality - the percent of JPEG compression
    • min: 1
    • max: 100
    • default: 50
  • targetWidth - maximal width of a picture
    • min: 10
    • max: 7000
    • default: no fixed value, depends on resolution of device camera
  • targetHeight - maximal height of a picture
    • min: 10
    • max: 7000
    • default: no fixed value, depends on resolution of device camera
  • The quality of the picture set to '50' by default. The maximum supported size of the photo is 8Mb. If the photo exceeds this value, the error 'CODE_TAKE_PHOTO_FILE_IS_TOO_LARGE' is returned.
  • Please take into account that the size of the picture can influence the device's performance.
  • The targetWidth and targetHeight parameters can be used to resize the final picture. The aspect ratio won't be changed, and the picture can be reduced or increased in size in order to fit the target width and target height.

Example of ready method with the "sendMessageAsJsObject" flag (Plugin -> OFS):


{
    "apiVersion": 1,
    "method": "ready",
     ...
    "sendMessageAsJsObject": true
}

Example of open method with the availability of the "takePhoto" procedure that reflects that the "takePhoto" procedure is available: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "open",
     ...
    "allowedProcedures": {
        ...
        "takePhoto": true
        }
}

Example of the calling of the "takePhoto" procedure: (Plugin -> OFS)


{
    "apiVersion": 1,
    "method": "callProcedure",
    "callId": "123",
    "procedure": "takePhoto"
}

Example of the calling of the "takePhoto" procedure with params: (Plugin -> OFS)


{
    "apiVersion": 1,
    "method": "callProcedure",
    "callId": "123",
    "procedure": "takePhoto",
    "params": {
            "quality": 50,
            "targetWidth": 1000,
            "targetHeight": 1000
            }
}

Success response

Any success response will contain a "cancelled" field with the boolean value. In the case of where the photo has been taken and was sent to a plugin, the result will contain a "photo" field with a Blob file of the photo.

Example of the "takePhoto" procedure calling result: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "123",
    "resultData": {
            "cancelled": false,
            "photo": [Blob]
        } 
}

Example of the "takePhoto" procedure calling the result in case the camera was closed without a photo: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "123",
    "resultData": {
            "cancelled": true
        } 
}

Error response

Error responses will include an error type and an error code. The following errors can be returned:

TYPE_INTERNAL CODE_UNKNOWN - Common errors
TYPE_MESSAGE_FORMAT CODE_METHOD_UNEXPECTED - Is returned if the plugin tries to run the "takePhoto" procedure while this procedure is already running. Plugin should wait for a result of this procedure before calling it again.
TYPE_PROCEDURE_ERROR CODE_PROCEDURE_UNAVAILABLE procedure Is returned if the procedure is not available. (i.e. OFS is not open in iOS/Android Mobile Application)
TYPE_PROCEDURE_ERROR CODE_PROCEDURE_JS_OBJECT_FLAG_REQUIRED procedure, data Is returned if the plugin tries to run the "takePhoto" procedure without plugin request to transfer data with the JS object (i.e. didn't send "sendMessageAsJsObject": true on "ready" method). "procedure" = procedure name, "data" = error message.
TYPE_PROCEDURE_ERROR CODE_PROCEDURE_PARAMS_IS_NOT_OBJECT procedure Is returned if the "params" item was sent and it is not an object.
TYPE_PROCEDURE_TAKE_PHOTO_ERROR CODE_TAKE_PHOTO_FILE_IS_TOO_LARGE procedure, data Is returned if the photo file that is returned by the camera is larger than 8Mb (for example if quality parameter is too high). "procedure" = procedure name, "data" = error message.
TYPE_PROCEDURE_TAKE_PHOTO_ERROR CODE_PROCEDURE_FAILED procedure, data Any other error that is not listed here. "procedure" = procedure name, "data" = error message.
TYPE_PROCEDURE_PARAM CODE_PROCEDURE_PARAM_VALUE_INVALID procedure, paramName Is returned if:
  • quality is out of range (1..100)
  • targetWidth is out of range (10..7000)
  • targetHeight is out of range (10..7000)

Example of an error if the procedure "takePhoto" is called from plugin that was opened not from the native Android/iOS App, or the procedure "takePhoto" is called on the OFS platform: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "error",
    "errors": [
                {
                    "type": "TYPE_PROCEDURE_ERROR",
                    "code": "CODE_PROCEDURE_UNAVAILABLE",
                    "procedure": "takePhoto"
                }
              ],
    "callId": "123"
}

Example of an error where the procedure "takePhoto" is called with "params" that is not an object: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "error",
    "errors": [
                {
                    "type": "TYPE_PROCEDURE_ERROR",
                    "code": "CODE_PROCEDURE_PARAMS_IS_NOT_OBJECT",
                    "procedure": "takePhoto"
                }
              ],
    "callId": "123"
}

Example of an error where the procedure "takePhoto" is called with a "quality", "targetWidth" or "targetHeight" parameter that is not an integer, or if the value is larger or smaller than the minimum or maximum values: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "error",
    "errors": [
                {
                    "type": "TYPE_PROCEDURE_PARAM",
                    "code": "CODE_PROCEDURE_PARAM_VALUE_INVALID",
                    "procedure": "takePhoto",
                    "paramName": "quality"
                }
             ],
    "callId": "123"
}

Example of an error where the procedure "takePhoto" is called and the resulting file is too large: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "error",
    "errors": [
                {
                    "type": "TYPE_PROCEDURE_TAKE_PHOTO_ERROR",
                    "code": "CODE_TAKE_PHOTO_FILE_IS_TOO_LARGE",
                    "procedure": "takePhoto",
                    "data": "..."
                }
             ],
    "callId": "123"
}

Example of an error where the plugin is not requesting transfer with the JS object in "ready" method: (OFS -> Plugin)


{
    "apiVersion": 1,
    "method": "error",
    "errors": [
                {
                    "type": "TYPE_PROCEDURE_ERROR",
                    "code": "CODE_PROCEDURE_JS_OBJECT_FLAG_REQUIRED",
                    "procedure": "takePhoto",
                    "data": "..."
                }
             ],
    "callId": "123"
}

Example of an error for any other reason of procedure processing (OFS -> Plugin)


{
        "apiVersion": 1,
        "method": "error",
        "errors": [
            {
                "type": "TYPE_PROCEDURE_TAKE_PHOTO_ERROR",
                "code": "CODE_PROCEDURE_FAILED",
                "procedure": "takePhoto",
                "data": "..."
            }
                    ],
        "callId": "123"
}

Data transfer format (JSON / JS object)

The data between a Plugin and OFS can be transferred in two formats: as a JSON string (initially) and as a JS object (since 23C).

Transferring data as a JS object has a couple benefits that makes it more useful:

  • it allows the sending of files from OFS to a Plugin (in the case of the "takePhoto" procedure)
  • the data transferring is faster because there is no parsing and validation of the JSON format

It is highly recommended to send a "sendMessageAsJsObject": true item in "ready" method within all modern plugins.

OFS keeps information about the chosen variant of transfer in the browser's memory. So, if a "sendMessageAsJsObject":true flag was sent, OFS will transfer data as a JS object until either the "sendMessageAsJsObject": false is sent or while the browser tab is open.

Example of the "ready" message:


{
        "apiVersion": 1,
        "method": "ready",
        "sendMessageAsJsObject" :true
}