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

(inner) 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:
string packageName

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

(inner) 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:
string | null

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.

(inner) 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:
string | null

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.

(inner) 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:
object

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.

(inner) 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:
string apkPath

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

(inner) 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:
string packageName

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

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.

(inner) 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:
string activity

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

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:
boolean

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.

(inner) 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:
string packageName

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

(inner) 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:
string packageName

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

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

(inner) 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:
string packageName

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