app

Application control module for Android devices in the Total Control scripting system.

This module enables automation and control of Android apps running on connected devices. It provides
functionality to launch, close, install, uninstall, and query apps, as well as manipulate or retrieve
activities on the device. It supports both Java-layer and JS-layer extensions to the Device object,
allowing methods to be invoked via device.runApp() or directly through exports.

Features

  • Launch and restart applications by package name
  • Close apps or check if an app is running in the foreground
  • Retrieve the currently focused app or activity
  • Install or uninstall APK files from a specified path
  • Get a list of all installed packages on the device
  • Dynamically open activities by component name with or without root

Usage Example

var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();

// Run an application
var result = sigmaDevice.runApp("com.tencent.qqmusic");
if (result === 0) {
  print("App launched successfully");
}

// Get currently focused activity
var { getActivity } = require("sigma/app");
var activity = getActivity();
print("Current activity: " + activity);

Integration

  • Methods are automatically bound to Device.prototype and DeviceArray.prototype

Methods

(static) closeApp(packageName) → {number}

Close specified software on the device.

Example
var app = require("sigma/app");
var runAppName = "com.tencent.qqmusic";
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
var closeapp = sigmaDevice.closeApp(runAppName);
if (closeapp === 0) {
  print("Succeed to close QQmusic");
} else {
  print("Failed to close QQmusic");
}

// Operation Result:
// If it executes successfully, it will return:
Succeed to close QQmusic
Parameters:
Name Type Description
packageName string

The package name of the app to close, e.g. "com.tencent.qqmusic".
Returns:
  • 0: Successfully closed the specified app.
  • -1: Closing the specified app failed, specific error information can be obtained by the lastError() function.
Type
number

(static) getActivity() → {string|null}

Gets the currently running activity.

It prioritizes matching the most relevant activity keys:

  • topResumedActivity
  • ResumedActivity
  • TopResumedActivity
Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
// Example: Get activity from main device
var sigmaDevice = Device.getMain();
if (!sigmaDevice) {
  print("No device found");
} else {
  const ret = sigmaDevice.getActivity();
  print("The activity running in the foreground is: " + ret);
}

// Operation Result:
// If it executes successfully, it will return:
The activity running in the foreground is: com.tencent.qqmusic/com.tencent.qqmusic.activity.LoginActivity
Returns:

This function returns the value of the activity if it succeeds, and returns null if it fails. If failed, specific error information can be obtained by the lastError() function.

Type
string | null

(static) getForegroundApp() → {string|null}

Get the name of the APP currently running on the device.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
if (sigmaDevice != null) {
  const ret = sigmaDevice.getForegroundApp();
  print("The app running in the foreground of the phone is: " + ret);
} else {
  print("No device found");
}

// Operation Result:
// If it executes successfully, it will return:
The app running in the foreground of the phone is: com.tencent.qqmusic
Returns:

This function returns the App package name if it succeeds, and returns null if it fails. If failed, specific error information can be obtained by the lastError() function.

Type
string | null

(static) getInstalledAPKList() → {object}

Get the name of the APP currently running on the device.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
print("All APKs currently installed on this phone are:");
var ret = sigmaDevice.getInstalledAPKList();
for (let i = 0; i < ret.length; i++) {
  print(ret[i]);
}

// Operation Result:
// If it executes successfully, it will return:
Congratulations, this API executes successfully.
Return value:
com.huawei.android.wfdft
com.android.wallpaper.livepicker
com.android.apps.tag
com.huawei.powergenie
com.android.settings
...
com.huawei.android.airsharing
com.alipay.mobile.scanx
Returns:

This function returns the name of all software installed on the phone if it succeeds, and returns null if it fails. If failed, specific error information can be obtained by the lastError() function.

Type
object

(static) installAPK(apkPath) → {number}

Installs an APK file on the connected device from the specified file path.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.installAPK("D:/Download/QQyinyue_850.apk");
if (ret !== 0) {
  print(lastError());
} else {
  print("Successfully installed APK");
}

// Operation Result:
// If it executes successfully, it will return:
Successfully installed APK
Parameters:
Name Type Description
apkPath string

The full file path to the APK file (e.g., "D:/Download/QQyinyue_850.apk").
Returns:
  • 0: Successful installation.
  • -1: Software installation failed, specific error information can be obtained by the lastError() function.
Type
number

(static) isAppForeground(packageName) → {number}

Determine whether the specified application is running in the foreground.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.isAppForeground("com.tencent.qqmusic");
if (ret !== 0) {
  print(lastError());
} else {
  print("The specified software is running in the foreground");
}

// Operation Result:
// If it executes successfully, it will return:
The specified software is running in the foreground
Parameters:
Name Type Description
packageName string

The package name of the application to check, e.g. "com.tencent.qqmusic".
Returns:

Returns 0 if running in the foreground, otherwise returns non-zero. At this point, the lastError() function can be used to get the specific error message.

Type
number

(static) openActivity(activity, administrator) → {boolean}

Open the specified activity.

Example
var { Device } = require('sigma/device');
var app = require("sigma/app");
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.openActivity("com.tencent.qqmusic/com.tencent.qqmusic.activity.AppStarterActivity", false);
if (ret === true) {
  print("Successfully opened the specified activity");
} else {
  print("Failed to open the specified activity");
}

// Operation Result:
// If it executes successfully, it will return:
Successfully opened the specified activity
Parameters:
Name Type Description
activity string

The full activity name in the format "package/class", e.g. "com.tencent.qqmusic/com.tencent.qqmusic.activity.AppStarterActivity".
administrator boolean

Whether to get super permissions.
Some devices require root privileges to open an activity, this type of device first needs to be rooted, and then set the administrator value to true.
If the device can open the activity without root privileges, set the administrator value to false.
Returns:

This function returns true if it succeeds, and returns false if it fails. If failed, specific error information can be obtained by the lastError() function.

Type
boolean

(static) restartApp(packageName) → {boolean}

Restarts the specified application on the device by its package name.
It will first attempt to force stop the app and then relaunch it.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var runAppName = "com.tencent.qqmusic";
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.restartApp(runAppName);
if (ret === 0) {
  print("Succeed to restart qqmusic");
} else {
  print(lastError());
}

// Operation Result:
// If it executes successfully, it will return:
Succeed to restart qqmusic
Parameters:
Name Type Description
packageName string

The package name of the app to restart (e.g., "com.tencent.qqmusic").
Returns:
  • true: Successfully restarted the specified app.
  • false: Restarting the specified app failed, specific error information can be obtained by the lastError() function.
Type
boolean

(static) runApp(packageName) → {number}

Launches the specified application on the device by its package name.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var runAppName = "com.tencent.qqmusic";
var sigmaDevice = Device.getMain();
var runapp = sigmaDevice.runApp(runAppName);
if (runapp === 0) {
  print("Succeed to run qqmusic");
} else {
  print(lastError());
}

// Operation Result:
// If it executes successfully, it will return:
Succeed to run qqmusic
Parameters:
Name Type Description
packageName string

The package name of the app to run (e.g., "com.tencent.qqmusic").
Returns:

Returns 0 if the app was successfully launched, or a non-zero value if the launch failed.

Type
number

(static) uninstallAPK(packageName) → {number}

Uninstalls the specified application from the device using its package name.

Example
var app = require("sigma/app");
var { Device } = require('sigma/device');
var sigmaDevice = Device.getMain();
var ret = sigmaDevice.uninstallAPK("com.tencent.qqmusic");
if (ret === 0) {
  print("Successfully uninstall APK");
} else {
  print(lastError());
}

// Operation Result:
// If it executes successfully, it will return:
Successfully uninstall APK
Parameters:
Name Type Description
packageName string

The package name of the app to uninstall (e.g., "com.tencent.qqmusic").
Returns:
  • 0: Successfully run the specified app.
  • -1: Running the specified app failed, specific error information can be obtained by the lastError() function.
Type
number