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:
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);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. |
This feature is only available for Android devices with camera.
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 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. |
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.
|
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);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.
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.
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.
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.
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);
}/*
* 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();
};