Action.launchForResult()

Overview

Launches an Android Activity that allows the Client to interact with other software loaded on the device.

Calls to Action.launchForResult() are asynchronous and the script will continue to execute even through the activity has not returned. The function passed as the second parameter will be invoked when the activity completes. Only one outstanding Activity launched for result should be active at a time.

Activities are started using intents. The intent is represented as a JavaScript object with certain properties.

  • Intents must have at least an action or a class and package combination.
  • If multiple applications match the intent, a chooser dialog will appear.

This action is not applicable to iOS.

Format

var resultCallback = function(resultIntent) { /*...*/ };

Action.launchForResult(intent, resultCallback);
Parameter Description Type Required
intent Describes the activity or action and associated information. Object Required
resultCallback A callback used when the activity returns. Function Required
resultIntent Describes the results of the activity or action. This is a parameter for resultCallback. Object Required

Intent object properties

Value Description Type Required Notes
action A string representing the action to be performed. String Optional If the device has multiple apps registered to handle an action, a chooser dialog appears.
categories A list of required categories for the activity that is being started. Array of strings Optional
class The name of the activity class to explicitly launch. String Optional Must be used with package.
package The name of the application package to explicitly launch. String Optional Must be used with class.
data The data URI that the action will operate on. String Optional Must be a URI formatted string. For example:
"http://www.wavelink.com/"
"file:///sdcard/file.dat"

In Android 11 or newer, the Velocity client has very limited access to the file system.


Added in version 2.1.1
mime The explicit MIME type of the data, or, if no data is specified, a request for a specific MIME type result. String Optional Rarely used.
For example:
"text\plain"
Added in version 2.1.1
extras Passes additional data to the invoked app. Array of objects Optional

See the description for Extras in the table below.
result A number representing the returned result from the launched activity. Number Part of the resultIntent A value of -1 indicates that the operation succeeded. A value of 0 indicates the operation was canceled. Values of 1 or greater indicate custom defined values for the result of the operation.

Extras

Value Description Type Required Notes
name The name of the extra. String Required  
value The value of the extra. String, Integer, Boolean, array of String, array of Integer, array of Boolean Required arrays added in version 2.1.11
type The value type. One of "string", "integer", or "boolean". String Optional If not specified, a type will be assigned based on the JavaScript type of the first value in arrays. For arrays, use the same three types to represent the type for all values in the array.

Example

Copy 
/* Launch Barcode scanning application, send results as a scan to the host.
 */
Action.launchForResult({
      action: 'com.google.zxing.client.android.SCAN',
      extras: [
         {name:'scanMode', value:'SCAN_MODE', type:'string'}
      ]
   },
   function (intent) {
      if(intent.result === -1) {
         var scanData;
         var scanType;
         for(var extra in intent.extras) {
            if(intent.extras[extra].name === 'SCAN_RESULT')

                scanData = intent.extras[extra].value;
            if(intent.extras[extra].name === 'SCAN_RESULT_FORMAT')

                scanType = intent.extras[extra].value;
         }
         if(scanData && scanType) {

            Device.fakeScan(scanType, scanData);
         }
      }
    }
);