JavaScript Extensibility API Reference Guide

Device specific

Android camera to scan barcodes/QR codes

Overview

The Simphony Android POS client has the capability to read barcodes and QR codes from Android device’s camera using the third party library Google MLkit.

The key functions of the Android Barcode scanner feature are:

  • The Android POS application opens the camera with a button click.
  • SimphonyExtensibilityAPI is used to subscribe to Barcode events
  • When a barcode or QR code is scanned, the POS sends the Extensibility Barcode event to all subscribed JavaScript Extensibility scripts.
  • The JavaScript Extensibility scripts examine the Barcode data. They might display or use the data, the format and the type of Barcode or QR code on Ops.

Subscribing to Barcode Scanner Events

JavaScript Extensibility scripts use the standard model for subscribing to POS events. JavaScript Extensibility scripts use the standard model for subscribing to POS events.

var _api = SimphonyExtensibilityAPI;
_api.Eventing.SubscribeToEvent('OpsBarcodePreviewEvent', OnOpsBarCodeEvent);

Consuming Barcode Scanner Events

The Barcode Scanner event follows the standard SIM event method signature. The args are of type OpsBarcodePreviewEventArgs.

function OnOpsBarCodeEvent(sender, args)
{
    if (!args.Handled)
    {
        args.Handled = true;
        
        if (args.BarcodeString != null)
        {
            showMessage('Barcode' + args.BarcodeType +',' + args.BarcodeFormat + ',' + args.BarcodeString + ',' + args.RawBarcodeString );
        }
        else
        {
            showMessage('No Barcode scanned!');
        }
    }

    return _api.Eventing.Continue;
}

All JavaScript Extensibility scripts that subscribe to this event are executed. It is critical to validate that no other JavaScript Extensibility script has consumed this data. It is also important for JavaScript Extensibility scripts to set Handled to true, so that Barcode events are not processed twice. This should only be done if the JavaScript Extensibility event consumes the Barcode scanner data.

Notes on OpsBarcodePreviewEventArgs:

Property Description
bool ManuallyEntered true if the barcode is keyed in rather than scanned, using an Ops command.
BarcodeType Get the barcode or QR code type, see Barcode Types below.
BarcodeFormat Get the barcode or QR code format, see Barcode Formats below.
string BarcodeString Get the barcode or QR code string data.
string RawBarcodeString Sometimes the barcode or QR code string data is set as rawdata.
bool Handled Set to true when a JavaScript Extensibility script consumes this Barcode.

Barcode Formats

  • Barcode.FORMAT_UNKNOWN
  • Barcode.FORMAT_ALL_FORMATS
  • Barcode.FORMAT_CODE_128
  • Barcode.FORMAT_CODE_39
  • Barcode.FORMAT_CODE_93
  • Barcode.FORMAT_CODABAR
  • Barcode.FORMAT_DATA_MATRIX
  • Barcode.FORMAT_EAN_13
  • Barcode.FORMAT_EAN_8
  • Barcode.FORMAT_ITF
  • Barcode.FORMAT_QR_CODE
  • Barcode.FORMAT_UPC_A
  • Barcode.FORMAT_UPC_E
  • Barcode.FORMAT_PDF417
  • Barcode.FORMAT_AZTEC

Barcode Types

  • Barcode.TYPE_UNKNOWN
  • Barcode.TYPE_CONTACT_INFO
  • Barcode.TYPE_EMAIL
  • Barcode.TYPE_ISBN
  • Barcode.TYPE_PHONE
  • Barcode.TYPE_PRODUCT
  • Barcode.TYPE_SMS
  • Barcode.TYPE_TEXT
  • Barcode.TYPE_URL
  • Barcode.TYPE_WIFI
  • Barcode.TYPE_GEO
  • Barcode.TYPE_CALENDAR_EVENT
  • Barcode.TYPE_DRIVER_LICENSE

Limitations

This feature is only available for Android devices with camera.

Sample JavaScript Extensibility Script

var _api = SimphonyExtensibilityAPI;
_api.Eventing.SubscribeToEvent('OpsBarcodePreviewEvent', OnOpsBarCodeEvent);

//The button should be configured as Function | Sim Inquire. The button "Argument" should be <extAppName>:scanbarcode
globalThis.scanbarcode = function ()
{
    // Open the camera and allow a barcode scan
    _api.Environment.Context.CameraScanBarcodeOpen()
}

function OnOpsBarCodeEvent(sender, args)
{
    if (!args.Handled)
    {
        args.Handled = true;
        
        if (args.BarcodeString != null)
        {
            showMessage('Barcode' + args.BarcodeType +',' + args.BarcodeFormat + ',' + args.BarcodeString + ',' + args.RawBarcodeString );
        }
        else
        {
            showMessage('No Barcode scanned!');
        }
    }

    return _api.Eventing.Continue;
}


function showMessage(msg)
{
    let line = `${_api.Runtime.ApplicationName}: ${msg}`;
    _api.Environment.Context.ShowMessage(line);
}

Android App-Switching API

Overview

Android JavaScript Extensibility allows JavaScript extensions to launch Android applications and system activities through the current Android Activity.

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;
const appContext = _api.Platform.Android.ApplicationContext;
Method / Property Description
Helper Creates Android objects and invokes Android/Java methods through reflection.
Activity Provides the current Android Activity used to launch applications and activities.
ApplicationContext Provides application-level context for package, file, preference, and system-service operations.

App-Switching Capabilities for API Users

The Android JSE API allows JavaScript extensions to initiate communication with other Android applications through the current ServiceHost Activity. API users can launch installed applications, pass data through Intent extras, and optionally receive a result from the target application.

The current implementation supports outbound app switching initiated by ServiceHost. Receiving external Intents, exposing deep links or requesting permissions that are not already declared are not supported.

ApplicationContext is intended for application-level operations such as package, file, preference, and system-service access. The current Activity must be used for launching another application or system activity.

API user capability Notes
Launch another installed application Use GetLaunchIntentForPackage() and StartActivity().
Launch a specific Activity The target Activity must be accessible to external applications.
Pass data to another application Use Intent extras or a Bundle.
Receive a result from another application Use StartActivityForResult() and OpsAndroidActivityResultEvent.
Return status, transaction data, or errors The target application must call setResult() and finish().
Open a URL or system settings screen Use an appropriate VIEW or settings Intent.
Share text with another application Use the SEND action.

Creating and Launching an Intent

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;

const intent = helper.CreateInstance("Android.Content.Intent");

intent.SetAction("android.intent.action.VIEW");

const uri = helper.CallStaticMethod(
    "Android.Net.Uri",
    "Parse",
    "https://www.example.com"
);

intent.SetData(uri);
activity.StartActivity(intent);

Launching Another Application by Package Name

The recommended flow is to resolve the target application’s launch Intent through PackageManager and then start it.

const _api = SimphonyExtensibilityAPI;
const activity = _api.Platform.Android.Activity;

function launchApplication(packageName) {
    const packageManager = activity.PackageManager;
    const launchIntent = packageManager.GetLaunchIntentForPackage(packageName);

    if (!launchIntent) {
        throw new Error("Application is not installed: " + packageName);
    }

    activity.StartActivity(launchIntent);
}

launchApplication("com.example.partnerapp");

The package name must identify an application installed on the device.

Launching a Specific Activity

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;

function launchActivity(packageName, activityName) {
    const intent =
        helper.CreateInstance("Android.Content.Intent");

    intent.SetClassName(packageName, activityName);
    activity.StartActivity(intent);
}

Resolving the application’s launch Intent is preferred when the activity class name is not part of the integration contract.

Passing Data to the Target Application

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;

const intent =
    helper.CreateInstance("Android.Content.Intent");

intent.SetClassName(
    "com.example.partnerapp",
    "com.example.partnerapp.MainActivity"
);

intent.PutExtra("transaction_id", "TXN_10001");
intent.PutExtra("amount", "100.00");
intent.PutExtra("merchant_id", "MERCHANT_123");
intent.PutExtra("source_app", "ServiceHost");

const bundle =
    helper.CreateInstance("Android.OS.Bundle");

bundle.PutString("custom_data", "test_value");
bundle.PutBoolean("debug_mode", true);

intent.PutExtras(bundle);
activity.StartActivity(intent);

The sending and receiving applications must agree on extra names, data types, and their meaning.

Receiving a Result from Another Application

Use StartActivityForResult() when the target application must return information.

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;

const requestCode = 3001;

_api.Eventing.SubscribeToEvent(
    "OpsAndroidActivityResultEvent",
    onActivityResult
);


activity.StartActivityForResult(intent, requestCode);

function onActivityResult(sender, args) {
    if (args.Handled) {
        return;
    }

    const result = args.ActivityResult;

    if (result.RequestCode !== 3001) {
        return;
    }

    if (result.ResultCode === -1 && result.Intent) {
        const status =
            result.Intent.GetStringExtra("status");

        const approvalCode =
            result.Intent.GetStringExtra("approval_code");

        const message =
            result.Intent.GetStringExtra("message");

        // Process the successful response.
    } else if (result.ResultCode === 0) {
        // The target application was cancelled.
    }

    args.Handled = true;
}

Use a unique request code for each app-switching operation. The returned Intent may contain status, transaction identifier, approval code, error information, and other integration-specific extras.

Sharing Text

const _api = SimphonyExtensibilityAPI;
const helper = _api.Platform.Android.Helper;
const activity = _api.Platform.Android.Activity;

function shareText(text, subject) {
    const intent =
        helper.CreateInstance("Android.Content.Intent");

    intent.SetAction("android.intent.action.SEND");
    intent.SetType("text/plain");
    intent.PutExtra("android.intent.extra.TEXT", text);

    if (subject) {
        intent.PutExtra(
            "android.intent.extra.SUBJECT",
            subject
        );
    }

    const chooser =
        helper.CallStaticMethod(
            "Android.Content.Intent",
            "CreateChooser",
            intent,
            "Share using"
        );

    activity.StartActivity(chooser);
}

JSE example for android app switching

/*
 * Minimal Android JSE Internal Test
 *
 * Tests:
 * 1. Launch partner application
 * 2. Pass Intent extras
 * 3. Receive partner ActivityResult
 * 4. Request CAMERA permission
 * 5. Launch camera
 * 6. Receive camera ActivityResult
 * 7. Subscribe to Broadcast events
 * 8. Write results to OPS logs
 *
 * Public entry point:
 *
 *     RunRequiredAppSwitchSample()
 *
 * Update PARTNER_PACKAGE before testing.
 */

const _api = SimphonyExtensibilityAPI;
const _ctx = _api.Environment.Context;
const _helper = _api.Platform.Android.Helper;
const _activity = _api.Platform.Android.Activity;

const PARTNER_PACKAGE = "com.companyname.partnerapp";

const PARTNER_REQUEST_CODE = 7001;
const CAMERA_REQUEST_CODE = 7002;

const RUN_ID = "RUN-" + Date.now().toString(36).toUpperCase();

let testRunning = false;

const eventLogged = {
    ActivityResultEvent: false,
    IncomingIntentEvent: false,
    BroadcastEvent: false
};

/* -------------------------------------------------------------------------- */
/* Logging                                                                    */
/* -------------------------------------------------------------------------- */
function safeString(value) {
    try {
        if (value === null || value === undefined) {
            return "null";
        }

        return String(value);
    } catch (error) {
        return "[unprintable]";
    }
}

function safeError(error) {
    if (!error) {
        return "unknown";
    }

    return error.message
        ? error.message
        : String(error);
}

function opsLog(testName, status, details) {
    const message =
        "[JSE-API-TEST]" +
        " run=" + RUN_ID +
        " test=" + testName +
        " status=" + status +
        " details=" + safeString(details);

    try {
        _api.Logger.Log(message);
    } catch (error) {
        // Do not interrupt testing if OPS logging fails.
    }
}

function showFinalMessage(message) {
    _ctx.ShowMessage(
        "[JSE-API-TEST] " + message
    );
}

function logEventOnce(eventName, details) {
    if (eventLogged[eventName]) {
        return;
    }

    eventLogged[eventName] = true;

    opsLog(
        eventName,
        "INFO",
        details
    );
}

/* -------------------------------------------------------------------------- */
/* Event subscriptions                                                        */
/* -------------------------------------------------------------------------- */
_api.Eventing.SubscribeToEvent(
    "OpsAndroidActivityResultEvent",
    onActivityResult
);

_api.Eventing.SubscribeToEvent(
    "OpsAndroidBroadcastEvent",
    onBroadcast
);

opsLog(
    "ScriptInitialization",
    "PASS",
    "event subscriptions registered"
);

/* -------------------------------------------------------------------------- */
/* Activity result event                                                      */
/* -------------------------------------------------------------------------- */
function onActivityResult(sender, args) {
    logEventOnce(
        "ActivityResultEvent",
        "OpsAndroidActivityResultEvent received"
    );

    if (args.Handled) {
        return;
    }

    const result = args.ActivityResult;

    if (!result) {
        args.Handled = true;

        opsLog(
            "ActivityResult",
            "FAIL",
            "ActivityResult is null"
        );

        showFinalMessage(
            "ActivityResult was null."
        );

        testRunning = false;
        return;
    }

    opsLog(
        "ActivityResult",
        "INFO",
        "requestCode=" +
        result.RequestCode +
        " resultCode=" +
        result.ResultCode
    );

    if (
        result.RequestCode === PARTNER_REQUEST_CODE
    ) {
        handlePartnerResult(result);
        args.Handled = true;
        return;
    }

    if (
        result.RequestCode === CAMERA_REQUEST_CODE
    ) {
        handleCameraResult(result);
        args.Handled = true;
        return;
    }

    opsLog(
        "ActivityResult",
        "INFO",
        "unrecognized requestCode=" +
        result.RequestCode
    );

    args.Handled = true;
}

/* -------------------------------------------------------------------------- */
/* Broadcast event                                                            */
/* -------------------------------------------------------------------------- */
function onBroadcast(sender, args) {
    let action = "unknown";

    try {
        if (
            args.BroadcastResult &&
            args.BroadcastResult.Intent
        ) {
            action =
                args.BroadcastResult.Intent.Action ||
                "unknown";
        }
    } catch (error) {
        action = "unreadable";
    }

    logEventOnce(
        "BroadcastEvent",
        "OpsAndroidBroadcastEvent received; action=" +
        action
    );

    // No popup is displayed.
    // Do not mark handled so normal host processing can continue.
}

/* -------------------------------------------------------------------------- */
/* Partner application                                                        */
/* -------------------------------------------------------------------------- */
function launchPartnerApplication() {
    try {
        const packageManager =
            _activity.PackageManager;

        const intent =
            packageManager.GetLaunchIntentForPackage(
                PARTNER_PACKAGE
            );

        if (!intent) {
            opsLog(
                "PartnerApplication",
                "SKIP",
                "not installed: " +
                PARTNER_PACKAGE
            );

            showFinalMessage(
                "Partner application is not installed.\n" +
                "Proceeding to camera test."
            );

            launchCamera();
            return;
        }

        intent.PutExtra(
            "transaction_id",
            RUN_ID
        );

        intent.PutExtra(
            "amount",
            "100.00"
        );

        intent.PutExtra(
            "merchant_id",
            "TEST_MERCHANT"
        );

        intent.PutExtra(
            "source_app",
            "ServiceHost"
        );

        _activity.StartActivityForResult(
            intent,
            PARTNER_REQUEST_CODE
        );

        opsLog(
            "PartnerApplication",
            "PASS",
            "launched requestCode=" +
            PARTNER_REQUEST_CODE
        );
    } catch (error) {
        opsLog(
            "PartnerApplication",
            "SKIP",
            "launch unavailable: " +
            safeError(error)
        );

        showFinalMessage(
            "Partner application is unavailable.\n" +
            "Proceeding to camera test."
        );

        launchCamera();
    }
}

function handlePartnerResult(result) {
    let status = "UNKNOWN";
    let transactionId = "null";
    let message = "null";
    let approvalCode = "null";

    if (result.Intent) {
        status =
            result.Intent.GetStringExtra(
                "status"
            ) || status;

        transactionId =
            result.Intent.GetStringExtra(
                "transaction_id"
            ) || transactionId;

        message =
            result.Intent.GetStringExtra(
                "message"
            ) || message;

        approvalCode =
            result.Intent.GetStringExtra(
                "approval_code"
            ) || approvalCode;
    }

    opsLog(
        "PartnerResult",
        result.ResultCode === -1
            ? "PASS"
            : "INFO",
        "resultCode=" +
        result.ResultCode +
        " status=" +
        status +
        " transactionId=" +
        transactionId +
        " approvalCode=" +
        approvalCode +
        " message=" +
        message
    );

    if (result.ResultCode !== -1) {
        showFinalMessage(
            "Partner application cancelled."
        );

        testRunning = false;
        return;
    }

    opsLog(
        "PartnerResult",
        "INFO",
        "partner result received; starting camera test"
    );

    launchCamera();
}

/* -------------------------------------------------------------------------- */
/* Camera                                                                    */
/* -------------------------------------------------------------------------- */
function launchCamera() {
    try {
        const permission =
            "android.permission.CAMERA";

        const granted =
            _helper.CheckPermission(permission);

        opsLog(
            "CameraPermission",
            "INFO",
            "granted=" + granted
        );

        if (granted) {
            startCameraActivity();
            return;
        }

        _helper.RequestPermission(
            permission,
            function (permissionGranted) {
                opsLog(
                    "CameraPermissionCallback",
                    permissionGranted
                        ? "PASS"
                        : "FAIL",
                    "granted=" +
                    permissionGranted
                );

                if (permissionGranted) {
                    startCameraActivity();
                } else {
                    showFinalMessage(
                        "Camera permission was denied."
                    );

                    testRunning = false;
                }
            }
        );
    } catch (error) {
        opsLog(
            "CameraPermission",
            "FAIL",
            safeError(error)
        );

        showFinalMessage(
            "Camera permission failed: " +
            safeError(error)
        );

        testRunning = false;
    }
}

function startCameraActivity() {
    try {
        const intent =
            _helper.CreateInstance(
                "Android.Content.Intent"
            );

        intent.SetAction(
            "android.media.action.IMAGE_CAPTURE"
        );

        const resolved =
            intent.ResolveActivity(
                _activity.PackageManager
            );

        if (!resolved) {
            opsLog(
                "CameraActivity",
                "SKIP",
                "no camera application available"
            );

            showFinalMessage(
                "No camera application is available."
            );

            testRunning = false;
            return;
        }

        _activity.StartActivityForResult(
            intent,
            CAMERA_REQUEST_CODE
        );

        opsLog(
            "CameraActivity",
            "PASS",
            "launched requestCode=" +
            CAMERA_REQUEST_CODE
        );
    } catch (error) {
        opsLog(
            "CameraActivity",
            "FAIL",
            safeError(error)
        );

        showFinalMessage(
            "Camera launch failed: " +
            safeError(error)
        );

        testRunning = false;
    }
}

function handleCameraResult(result) {
    if (result.ResultCode === -1) {
        let thumbnailAvailable = false;

        if (result.Intent) {
            try {
                const data =
                    result.Intent.GetParcelableExtra(
                        "data"
                    );

                thumbnailAvailable =
                    data !== null &&
                    data !== undefined;
            } catch (error) {
                opsLog(
                    "CameraResult",
                    "INFO",
                    "thumbnail was not available: " +
                    safeError(error)
                );
            }
        }

        opsLog(
            "CameraResult",
            "PASS",
            "camera completed; " +
            "thumbnailAvailable=" +
            thumbnailAvailable
        );

        showFinalMessage(
            "App-switching and camera tests completed successfully."
        );

        testRunning = false;
        return;
    }

    if (result.ResultCode === 0) {
        opsLog(
            "CameraResult",
            "INFO",
            "camera cancelled by user"
        );

        showFinalMessage(
            "Camera test was cancelled."
        );

        testRunning = false;
        return;
    }

    opsLog(
        "CameraResult",
        "FAIL",
        "unexpected resultCode=" +
        result.ResultCode
    );

    showFinalMessage(
        "Camera returned an unexpected result."
    );

    testRunning = false;
}

/* -------------------------------------------------------------------------- */
/* Single public test entry point                                             */
/* -------------------------------------------------------------------------- */
globalThis.RunRequiredAppSwitchSample =
    function () {
        if (testRunning) {
            showFinalMessage(
                "A test is already running."
            );

            return;
        }

        testRunning = true;

        opsLog(
            "RequiredAppSwitchSample",
            "START",
            "partner app and camera test started"
        );

        launchPartnerApplication();
    };