Skip to main content

app

老猫10/22/22About 7 min

The app module provides functions to use and interact with other apps, such as sending intents, opening files, and sending emails.

It also provides advanced helpers like startActivity and sendBroadcast to perform interactions not covered by the built-in convenience methods.

app.versionCode

  • {number}

Current app version code (integer), e.g. 160, 256.

If running inside Auto.js, this is the Auto.js version code; in a packaged app, this is the packaged app’s version code.

toastLog(app.versionCode);

app.versionName

  • {string}

Current version name, e.g. "3.0.0 Beta".

If running inside Auto.js, this is the Auto.js version name; in a packaged app, this is the packaged app’s version name.

toastLog(app.versionName);

app.autojs.versionCode

  • {number}

Auto.js version code (integer), e.g. 160, 256.

app.autojs.versionName

  • {string}

Auto.js version name, e.g. "3.0.0 Beta".

app.launchApp(appName)

  • appName {string} App name

Launches an app by its name. Returns false if no app matches; otherwise returns true. If multiple apps match, it launches one of them.

This function is also available globally.

launchApp("Auto.js");

app.launch(packageName)

  • packageName {string} Package name

Launches an app by its package name. Returns false if not installed; otherwise returns true.

This function is also available globally.

// Launch WeChat
launch("com.tencent.mm");

app.launchPackage(packageName)

  • packageName {string} Package name

Equivalent to app.launch(packageName).

app.getPackageName(appName)

  • appName {string} App name

Gets the package name of an installed app by its name. Returns null if not found. If multiple apps match, returns one of their package names.

This function is also available globally.

var name = getPackageName("QQ"); // returns "com.tencent.mobileqq"

app.getAppName(packageName)

  • packageName {string} Package name

Gets the app name of an installed app by its package name. Returns null if not found.

This function is also available globally.

var name = getAppName("com.tencent.mobileqq"); // returns "QQ"

app.openAppSetting(packageName)

  • packageName {string} Package name

Opens the app details page (system settings). Returns false if not found; otherwise returns true.

This function is also available globally.

app.getCurrentActivity()

  • Returns {Activity | null}

Returns the last recorded Activity object. If there is no foreground Activity context, it may return null.

log(app.getCurrentActivity());

app.getTopActivity()

  • Returns {Activity | null}

Returns the Activity at the top of the task stack. If no Activity is available, it may return null.

log(app.getTopActivity());

app.getFileProviderAuthority()

  • Returns {string}

Returns the FileProvider authority used by the current app.

log(app.getFileProviderAuthority());

app.getPathFromUri(uri)

  • uri {Uri} Uri object
  • Returns {string | null}

Tries to resolve a Uri into a file path. For some content:// Uris, it may return null or a path that is not directly accessible.

var uri = app.parseUri("file:///sdcard/1.txt");
log(app.getPathFromUri(uri));

app.sendLocalBroadcastSync(intent)

  • intent {Intent} Broadcast intent
  • Returns {void}

Sends a local broadcast synchronously. Typically used for communication between components inside the same app.

var i = app.intent({
  action: "com.example.LOCAL_TEST",
});
app.sendLocalBroadcastSync(i);

app.viewFile(path)

  • path {string} File path

Views a file using another app. If the file does not exist, it will be handled by the target viewing app.

If no app can handle viewing the file, it throws ActivityNotException.

// View a text file
app.viewFile("/sdcard/1.txt");

app.editFile(path)

  • path {string} File path

Edits a file using another app. If the file does not exist, it will be handled by the target editing app.

If no app can handle editing the file, it throws ActivityNotException.

// Edit a text file
app.editFile("/sdcard/1.txt/");

app.uninstall(packageName)

  • packageName {string} Package name

Uninstalls an app. A confirmation UI will be shown. If the package is not installed, the system uninstaller handles it and may show “App not found”.

// Uninstall QQ
app.uninstall("com.tencent.mobileqq");

app.openUrl(url)

  • url {string} Website URL. If it does not start with "http://" or "https://", "http://" is assumed.

Opens the URL in a browser.

If no browser is installed, it throws ActivityNotException.

app.sendEmail(options)

  • options {Object} Email options, including:
  • email {string} | {Array} Recipient email address(es)
  • cc {string} | {Array} CC recipient(s)
  • bcc {string} | {Array} BCC recipient(s)
  • subject {string} Subject
  • text {string} Body text
  • attachment {string} Attachment file path

Invokes an email app to send mail using options. All fields are optional.

If no email app is installed, it throws ActivityNotException.

// Send an email to 10086@qq.com and 10001@qq.com
app.sendEmail({
  email: ["10086@qq.com", "10001@qq.com"],
  subject: "Email subject",
  text: "Email body",
});

app.startActivity(name)

  • name {string} Activity name. Supported values:
    • console Console/log screen
    • settings Settings screen

Opens a specific Auto.js screen. When running inside Auto.js, it opens the corresponding screen in Auto.js; when running in a packaged app, it opens the corresponding screen in the packaged app.

app.startActivity("console");

app.intent(options)

  • options {Object} Options:

    • action {string} Intent action (what the intent wants to do). It's a string constant, e.g. "android.intent.action.SEND". If it starts with "android.intent.action", you can omit the prefix and use "SEND". See Actions.

    • type {string} Intent MIME type, describing the type of data associated with this intent, e.g. "text/plain".

    • data {string} Intent data URI, e.g. a file URI or URL. For example, to open a file: action="android.intent.action.VIEW", data="file:///sdcard/1.txt".

    • category {Array} Intent categories (rarely used). See Categories.

    • packageName {string} Target package name

    • className {string} Target component class name (Activity/Service/etc.)

    • extras {Object} Intent extras (key-value pairs). Provides additional data, e.g. email subject/body. See Extras.

    • flags {Array} Intent flags (string array), e.g. ["activity_new_task", "grant_read_uri_permission"]. See Flags.

      [v4.1.0 Added]

    • root {Boolean} Whether to start/send this intent with root privileges. When enabled, you should not use context.startActivity(); instead use helpers like app.startActivity({ ... }).

      [v4.1.0 Added]

Builds an Intent object from the given options.

Example:

// Open an app to view an image file
var i = app.intent({
  action: "VIEW",
  type: "image/png",
  data: "file:///sdcard/1.png",
});
context.startActivity(i);

Intent is a message-passing object you can use to request an action from another app component. Although intents can enable many kinds of component-to-component communication, the basic use cases are mainly:

  • Start an Activity: an Activity is a “screen” in an app. For example, an app’s entry screen is an Activity, and many features are separate Activities (WeChat home, Moments, chats, etc.). By passing an Intent to startActivity(), you can launch a new Activity instance. The Intent describes which Activity to launch and carries any required data.
  • Start a Service: a Service runs in the background without a UI. By passing an Intent to startService(), you can start a Service to perform one-off operations (e.g. downloading a file). The Intent describes which Service to start and carries any required data.
  • Send a broadcast: a broadcast is a message that any app can receive. The system sends broadcasts for system events (e.g. boot completed or charging). By passing an Intent to sendBroadcast(), sendOrderedBroadcast(), or sendStickyBroadcast(), you can broadcast a message to other apps.

Note: unless an app explicitly exposes an Activity, you generally cannot jump to a specific Activity/screen without root. For example, you can jump to QQ’s share screen because QQ exposes that Activity; but without root you typically cannot jump to QQ’s settings screen because that Activity is not exported.

If you have root, you can set "root": true in the intent options. For example, to open Auto.js settings with root:

app.startActivity({
  packageName: "org.autojs.autojs",
  className: "org.autojs.autojs.ui.settings.SettingsActivity_",
  root: true,
});

About discovering intent parameters: some intents are found accidentally and spread online (e.g. jumping to a QQ chat window because QQ provides a web-to-QQ-customer-service jump). If you want to discover an Activity’s intent parameters yourself, you can use techniques such as “intent recording”, “implicit start”, intercepting internal intents, or querying exported intents. Intercepting internal intents typically requires Xposed, or you can reverse-engineer the app to find parameters. There is no simple one-click way.

For more information, see Android guide: Intents and Intent Filters.

app.startActivity(options)

  • options {Object} Options

Builds an Intent from options and starts the Activity.

app.startActivity({
  action: "SEND",
  type: "text/plain",
  data: "file:///sdcard/1.txt",
});

app.sendBroadcast(options)

  • options {Object} Options

Builds an Intent from options and sends the broadcast.

app.startService(options)

  • options {Object} Options

Builds an Intent from options and starts the Service.

app.sendBroadcast(name)

[v4.1.0 Added]

  • name {string} Built-in broadcast name:
    • inspect_layout_hierarchy Inspect layout hierarchy
    • inspect_layout_bounds Inspect layout bounds

Sending these broadcasts triggers Auto.js layout inspection tools to help debugging. They only work when sent inside Auto.js; in packaged scripts they have no effect.

app.sendBroadcast("inspect_layout_bounds");

app.intentToShell(options)

[v4.1.0 Added]

  • options {Object} Options

Builds an Intent from options and converts it into arguments for the shell am intent command.

Example:

shell(
  "am start " +
    app.intentToShell({
      packageName: "org.autojs.autojs",
      className: "org.autojs.autojs.ui.settings.SettingsActivity_",
    }),
  true,
);

See Intent spec (adb/am).

app.parseUri(uri)

[v4.1.0 Added]

  • uri {string} A URI string, e.g. "file:///sdcard/1.txt", "https://www.autojs.org"
  • Returns {Uri} A Uri object. See android.net.Uri.

Parses the URI string and returns a Uri object. Even if the URI is malformed, this still returns a Uri object, but later accessing fields like scheme or path may yield null if parsing failed.

Note: on newer Android versions, the system restricts exposing absolute file paths in URIs. So if the input is a file://... URI, the returned Uri may be in content://... form.

app.currentActivity

  • {Activity | null}

Shortcut for the current Activity. Semantically equivalent to app.getCurrentActivity().

app.topActivity

  • {Activity | null}

Shortcut for the top Activity. Semantically equivalent to app.getTopActivity().

app.fileProviderAuthority

  • {string}

Shortcut for FileProvider authority. Semantically equivalent to app.getFileProviderAuthority().

app.packageName

  • {string | undefined}

Shortcut for the package name of the current script environment. You can think of it as a convenience form of app.getPackageName(app.appName).

app.appName

  • {string | undefined}

Shortcut for the app name of the current script environment (i.e. the app name corresponding to the current package name).

app.pathFromUri

  • {string | undefined}

Shortcut for the last URI path resolution result. In most cases, prefer calling app.getPathFromUri(uri) directly to get an explicit result.

app.getUriForFile(path)

[v4.1.0 Added]

  • path {string} File path, e.g. "/sdcard/1.txt"
  • Returns {Uri} A Uri object pointing to the file. See android.net.Uri.

Create a Uri object from a file path. Note that on newer Android versions, the system restricts exposing absolute file paths in URIs, so the returned Uri may be in content://... form.

app.getInstalledApps([options])

** [Added in Pro 8.0.0] **

  • options {Object} Options:
    • get: Specify what to include in returned app info
      • "activities" Activity components
      • "configurations" Hardware configurations
      • "gids" Group IDs
      • "instrumentation" Instrumentation info
      • "intent_filters" Intent filters
      • "meta_data" Meta-data (default)
      • "permissions" Permissions
      • "providers" ContentProvider components
      • "receivers" BroadcastReceiver components
      • "services" Service components
      • "shared_library_files" Shared library files
      • "signatures" Signatures (deprecated)
      • "signing_certificates" Signing certificates
      • "uri_permission_patterns"
      • "disabled_components" Apps disabled (still present)
      • "disabled_until_used_components" Components disabled until used
      • "uninstalled_packages" Uninstalled apps that still keep data
    • match: Specify which apps to match
      • "uninstalled_packages" Uninstalled apps that still keep data
      • "disabled_components" Disabled components/apps
      • "disabled_until_used_components" Disabled until used
      • "system_only" System apps only
      • "factory_only" Preinstalled apps only
      • "apex" APEX apps
  • Returns {Array<ApplicationInfo>}

Return a list of all app packages installed for the current user. If match includes uninstalled_packages, it also includes uninstalled apps that still keep data.

Returns an array of ApplicationInfo. If no apps are installed, returns an empty array.

match specifies which apps to include, and get specifies which information fields to include.

// Get system apps
let apps = $app.getInstalledApps({
  get: ["meta_data"],
  match: ["system_only"],
});
console.log(apps);

app.getInstalledPackages([options])

  • options {Object} Optional. Same filtering semantics as app.getInstalledApps([options]).
  • Returns {Array<string>}

Get the package name list of installed apps.
If options is omitted, it returns packages visible to the current user.

let packages = app.getInstalledPackages();
log("Package count: " + packages.length);
Copyright © 2026 老猫