App - Applications

The app module helps your script talk to other apps: intents, activities, services, broadcasts, opening files/URLs, email, and package queries.

startActivity and sendBroadcast are the main building blocks when there is no dedicated wrapper for a third-party screen or action.

Import the whole module:

const app = require("app");

Or import symbols you need:

const { startActivity, packageName } = require("app");

Table of contents

Interfaces

• BroadcastReceiver
• EmailOptions
• IntentOptions
• IntentOptionsWithRoot
• PMOptions

Variables

• packageName

Functions

• editFile
• getApkInfo
• getAppName
• getInstalledApps
• getInstalledPackages
• getPackageName
• getUriForFile
• intentToShell
• launch
• launchApp
• makeIntent
• openAppSettings
• openUrl
• parseUri
• registerBroadcastReceiver
• sendBroadcast
• sendEmail
• startActivity
• startService
• uninstall
• unregisterBroadcastReceiver
• viewFile

Variables

packageName

• packageName: string

The current host app’s package name.

In the Auto.js Pro IDE this is typically org.autojs.autojspro; in a packaged build it is your own application id.

Example

"nodejs";
const { packageName } = require("app");
console.log(packageName);

Functions

editFile

editFile(file: string): void

Hands the file to another app’s editor intent. Missing files are handled by that target app. If no editor can handle the type, an ActivityNotFoundException (or runtime equivalent) is thrown.

Example

"nodejs";
const app = require("app");
app.editFile("/sdcard/1.txt");

Parameters

Name	Type	Description
file	string	Path to the file to edit.

Returns

void

getApkInfo

getApkInfo(file: string, options?: PMOptions): android.content.pm.PackageInfo | null

Parses an APK on disk and returns PackageInfo, or null if the archive cannot be read.

See also

PackageManager.getPackageArchiveInfo

Example

"nodejs";
const app = require("app");
const info = app.getApkInfo("/path/to/apk", {
   get: ['meta_data'],
});
console.log(info.packageName);

Parameters

Name	Type	Description
file	string	Path to the .apk file.
options?	PMOptions	Flags controlling which metadata is filled in.

Returns

android.content.pm.PackageInfo | null

Parsed manifest metadata, or null on failure.

getAppName

getAppName(packageName: string): string | null

Returns the human-readable label of an installed app for the given package id, or null if it is not installed.

Parameters

Name	Type	Description
packageName	string	Target package name.

Returns

string | null

Display name, or null.

getInstalledApps

getInstalledApps(options?: PMOptions): android.content.pm.ApplicationInfo[]

Lists installed applications for the current user as ApplicationInfo objects. Returns an empty array if nothing matches.

Use options.match to filter which apps are included and options.get to request extra fields (e.g. metadata).

Example

"nodejs";
const app = require("app");
const apps = app.getInstalledApps({
    get: ['meta_data'],
    match: ['system_only']
});
console.log(apps);

See also

PackageManager.getInstalledApplications

Parameters

Name	Type	Description
options?	PMOptions	Filter and field flags.

Returns

android.content.pm.ApplicationInfo[]

Installed apps for the user. With match including uninstalled_packages, removed but data-retained apps may appear (per Android semantics).

getInstalledPackages

getInstalledPackages(options?: PMOptions): android.content.pm.PackageInfo[]

Same filtering idea as getInstalledApps, but each entry is a full PackageInfo.

See also

PackageManager.getInstalledPackages

Parameters

Name	Type	Description
options?	PMOptions	Filter and field flags.

Returns

android.content.pm.PackageInfo[]

Array of packages; empty if none match.

getPackageName

getPackageName(targetAppName: string): string | null

Resolves a visible app label to one installed package name. Returns null if no install matches. If several apps share the same label, one arbitrary package is returned.

Parameters

Name	Type	Description
targetAppName	string	Display name to search for.

Returns

string | null

Package id, or null.

getUriForFile

getUriForFile(pathOrUri: string): android.net.Uri

Builds a share-safe Uri for a filesystem path. On modern Android you usually get a content://… URI backed by FileProvider, not a raw file:// path.

Parameters

Name	Type	Description
pathOrUri	string	Absolute path such as /sdcard/1.txt, or an existing file:///… URI string.

Returns

android.net.Uri

Value suitable for Intent data / ClipData.

intentToShell

intentToShell(options: IntentOptions): string

Serializes IntentOptions into the argument fragment used by adb shell am … (or am under su).

See also

adb am

Example

"nodejs";
const { intentToShell } = require("app");
const { exec } = require("shell");
exec("am start " + intentToShell({
    packageName: "org.autojs.autojs",
    className: "org.autojs.autojs.ui.settings.SettingsActivity_"
}), { root: true});

Parameters

Name	Type	Description
options	IntentOptions	Intent fields to encode.

Returns

string

Shell snippet (no leading am verb).

launch

launch(packageName: string): boolean

Starts the app identified by package id. Returns false if the package is missing, true if a launch was requested.

Note: From the background, Android may block real UI startup even when this returns true. See the platform guide below.

See also

Background activity launches

Parameters

Name	Type	Description
packageName	string	Package to launch.

Returns

boolean

true if the package exists and a launch was issued—not a guarantee the foreground appeared.

launchApp

launchApp(targetAppName: string): boolean

Starts an app by label (same caveats as launch). If several packages share the label, one is picked non-deterministically.

Note: Background restrictions apply; see launch.

See also

Background activity launches

Parameters

Name	Type	Description
targetAppName	string	Installed app name as shown in the launcher.

Returns

boolean

Whether a matching package was found and a launch was requested.

makeIntent

makeIntent(options: IntentOptions): any

Builds a new Android Intent from high-level fields (action, data, packageName, className, extras, flags, …).

Typical uses

• Start an Activity — one “screen” of another app; call startActivity with the built intent (or use helpers that wrap this).
• Start a Service — background work; pair with startService.
• Send a broadcast — system or app events; pair with sendBroadcast.

Unless a target app exports the component you need, you cannot jump to arbitrary internal screens with a normal intent. Public share sheets work because the host app exposes them; private settings pages often do not. With root, add "root": true in options so the runtime can launch protected components—for example Auto.js Pro settings:

"nodejs";
const { startActivity } = require("app");
startActivity({
    packageName: "org.autojs.autojspro",
    className: "org.autojs.autojs.ui.settings.SettingsActivity",
    root: true
});

Example

"nodejs";
const app = require("app");
const i = app.makeIntent({
    action: "VIEW",
    type: "image/png",
    data: "file:///sdcard/1.png"
});
$autojs.androidContext.startActivity(i);

Parameters

Name	Type	Description
options	IntentOptions	Fields used to populate the Intent.

Returns

any

A new Intent instance.

openAppSettings

openAppSettings(packageName: string): boolean

Opens the system App info screen for packageName. Returns false if the package is not installed, otherwise true (subject to OEM behavior).

Parameters

Name	Type	Description
packageName	string	Package whose details page should open.

Returns

boolean

Whether the settings UI was requested successfully.

openUrl

openUrl(url: string): void

Opens url in a browser (or handler for http/https). Throws ActivityNotFoundException if no app can handle the link.

Parameters

Name	Type	Description
url	string	Must start with http:// or https://.

Returns

void

parseUri

parseUri(uri: any): android.net.Uri

Parses a URI string (or returns an existing URI object unchanged). Malformed input may still yield a Uri wrapper; later reads of getScheme(), getPath(), etc. may return null if parsing failed internally.

On recent Android, raw file://… paths are often rewritten to content://… FileProvider URIs for security.

Parameters

Name	Type	Description
uri	any	URI string or Android Uri instance.

Returns

android.net.Uri

Parsed (or echoed) URI.

registerBroadcastReceiver

registerBroadcastReceiver(filter: string | string[] | android.content.IntentFilter): BroadcastReceiver

Registers a dynamic receiver for system or third-party broadcasts. Use receiver.on("receive", listener) for each fired Intent. Always pair with unregisterBroadcastReceiver when done.

Example

"nodejs";
const { registerBroadcastReceiver, unregisterBroadcastReceiver } = require("app");

const receiver = registerBroadcastReceiver("android.intent.action.SCREEN_ON");

receiver.on("receive", (intent) => {
    console.log("Screen turned on");
    console.log("Intent action:", intent.getAction());
});

// unregisterBroadcastReceiver(receiver);

Example (multiple actions)

"nodejs";
const { registerBroadcastReceiver } = require("app");

const receiver = registerBroadcastReceiver([
    "android.intent.action.SCREEN_ON",
    "android.intent.action.SCREEN_OFF"
]);

receiver.on("receive", (intent) => {
    const action = intent.getAction();
    if (action === "android.intent.action.SCREEN_ON") {
        console.log("Screen turned on");
    } else if (action === "android.intent.action.SCREEN_OFF") {
        console.log("Screen turned off");
    }
});

Parameters

Name	Type	Description
filter	string | string[] | android.content.IntentFilter	One action (e.g. "android.intent.action.SCREEN_ON"), several actions, or a full IntentFilter.

Returns

BroadcastReceiver

Handle for on("receive", …); unregister when obsolete.

sendBroadcast

sendBroadcast(target: IntentOptionsWithRoot): Promise<void>

Builds an Intent from target and broadcasts it.

See also

makeIntent

Parameters

Name	Type	Description
target	IntentOptionsWithRoot	Full intent fields, plus optional root. If target is a string shortcut, built-in names include inspect_layout_hierarchy (layout tree dump) and inspect_layout_bounds (bounds overlay). These string shortcuts do not work inside packaged / store builds—they are IDE / debug helpers.

Returns

Promise<void>

Resolves after any root shell work finishes; resolves immediately when not using root. Does not wait for receivers to finish handling the broadcast.

sendEmail

sendEmail(options: EmailOptions): void

Opens the user’s mail composer with prefilled fields. Throws ActivityNotFoundException if no email client is installed.

Parameters

Name	Type	Description
options	EmailOptions	Recipients, subject, body, attachments, etc.

Returns

void

startActivity

startActivity(target: "console" | "settings" | IntentOptionsWithRoot): Promise<void>

Builds an Intent and starts the matching activity.

See also

makeIntent

Example

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

Parameters

Name	Type	Description
target	"console" | "settings" | IntentOptionsWithRoot	Either a shortcut string ("console" → log viewer activity, "settings" → settings activity) or a full intent specification (including optional "root": true).

Returns

Promise<void>

Same root-shell waiting rules as sendBroadcast. In all cases the promise resolves without waiting for the activity window to appear—it only tracks intent dispatch / shell completion.

startService

startService(target: IntentOptionsWithRoot): Promise<void>

Builds an Intent and requests service startup.

See also

makeIntent

Parameters

Name	Type	Description
target	IntentOptionsWithRoot	Service intent fields.

Returns

Promise<void>

Same root-shell semantics as above. Does not wait until the service’s onCreate() has finished.

uninstall

uninstall(packageName: string): void

Shows the system uninstall flow for packageName. If the package is missing, the uninstall UI may show a “app not found” style message.

Parameters

Name	Type	Description
packageName	string	Package to remove.

Returns

void

unregisterBroadcastReceiver

unregisterBroadcastReceiver(receiver: BroadcastReceiver): void

Unregisters a receiver returned by registerBroadcastReceiver. After this call, receiver stops getting events—unregister promptly to avoid leaks.

Example

"nodejs";
const { registerBroadcastReceiver, unregisterBroadcastReceiver } = require("app");

const receiver = registerBroadcastReceiver("android.intent.action.SCREEN_ON");

receiver.on("receive", (intent) => {
    console.log("Broadcast received");
});

setTimeout(() => {
    unregisterBroadcastReceiver(receiver);
    console.log("Broadcast receiver unregistered");
}, 10000);

Parameters

Name	Type	Description
receiver	BroadcastReceiver	Instance from registerBroadcastReceiver().

Returns

void

viewFile

viewFile(file: string): void

Opens file with a viewer app. Missing files are handled by the viewer. Throws ActivityNotFoundException if no handler exists.

"nodejs";
const app = require("app");
app.viewFile("/sdcard/1.txt");

Parameters

Name	Type	Description
file	string	Path to open.

Returns

void