• Go to the Home page
• Go to the v8 docs
• Go to the v9 docs

Automation

• Accessibility-based UI automation (recommended)
  • Find and act on controls (tap, long-press, swipe, type, …) via selectors.
  • Generally more stable across resolutions and devices.
  • Docs: v8 automator
• Coordinate and gesture automation
  • Fits games, canvas-like UIs, or views the accessibility tree cannot see well.
  • Clicks, swipes, multi-touch gestures, RootAutomator, etc.
  • Docs: coordinates-based automation
• Keys and system navigation
  • Back, home, recents, notification shade, etc. (accessibility or root).
  • Docs: keys

Native UI

• Rhino UI module (v8)
  • Declare layouts in XML: "ui"; plus $ui.layout(...).
  • Update widgets on the UI thread: $ui.post() / $ui.run().
  • Docs: v8 UI
• Custom widgets
  • Register reusable components with $ui.registerWidget() (properties, events, methods).
  • Docs: customWidget
• WebView / web-driven UI
  • Embed WebView, load local or remote pages, and bridge to scripts.
  • Docs: webview

Threads and concurrency

• threads module
  • Run heavy work off the main / UI thread.
  • Coordination patterns depend on version and APIs.
  • Docs: threads

Scheduling and background work

• Timed tasks (WorkManager)
  • Daily / weekly / one-shot / intent-triggered jobs.
  • Useful for schedules and “keep running” style scenarios (mind battery impact).
  • Docs: timedTasks
• Power management & battery optimization
  • Detect / request exemption from aggressive battery savers (use responsibly).
  • Docs: powerManager
• Internal toggles
  • e.g. “volume up stops script”, foreground-service notification, …
  • Docs: settings

Networking and realtime

• HTTP / WebSocket
  • OkHttp-based HTTP client patterns (requests, responses, …).
  • WebSocket for bidirectional, long-lived channels.
  • Docs: http, webSocket

Images and vision

• images module
  • Screenshots, read/write images, crop / scale / rotate / filters.
  • Color find, template find, feature matching (see version-specific docs).
  • Docs: images
• OCR
  • Pluggable engines (e.g. PaddleOCR, MLKit OCR, …).
  • Docs: ocr

Plugins

• Plugin store
  • Install and manage official and third-party plugins (OCR, 7-Zip, FFmpeg, …).
• Plugin SDK (advanced)
  • Ship custom native extensions and load them from scripts.
  • Docs: plugins, thirdPartyPlugins

Files and storage

• files module
  • Common read/write, copy/move, paths, text/bytes, file handles, …
  • Docs: files
• storages (local KV)
  • Simple persistent key–value storage shared across scripts (not for secrets).
  • Docs: storages

Packaging and engineering

• Project packaging
  • Package projects or scripts into standalone APKs (details depend on version and settings).
• Resources & Android assets (UI)
  • Use res/ assets, styles, etc. in UI (see UI API docs).
  • Docs: ui/api
• Encryption & protection
  • Packaging and toolchain options for stronger script protection (varies by engine).

Debugging and developer experience

• Console & logging
  • console.*, toastLog, …
  • Docs: console
• VSCode debugging
  • IDE-style debugging (depends on version and setup).
  • Docs: VSCode debugging tutorial

v8 vs v9

• v8: Rhino-first API and docs—great for quick scripts and classic UI flows.
• v9: Adds the Node.js 16.x runtime and a newer API surface (see v9 docs). Some patterns can still show memory leaks; treat v9 as optional unless you need npm / throughput—prefer v8 for everyday automation unless you know you need v9.

For the Node.js / v9 reference tree, open v9 reading guide from the sidebar.

By default, AI should prioritize the v8 (API v1 / Rhino) documentation when answering questions or generating code. The v9 (API v2 / Node.js) docs are recommended only for migration, compatibility analysis, or when the user explicitly requests v9. At the time of writing, v9 has a memory-leak risk and is not recommended as the default.

If you want answers in English, use the English-only llms files below (llms-en*.txt). They mirror the Chinese llms*.txt rules but include only pages under /en/, so the model sees English source text and stays aligned with English URLs. The site-wide index lists these under the english key in llms-index.json.

What is the LLM protocol?

The LLM protocol is a standardized way to provide structured documentation content to LLMs. By publishing a llms.txt file, a site can help AI access documentation more efficiently and reliably than crawling complex HTML.

Why do we need it?

LLMs increasingly rely on websites, but they have a key constraint: limited context windows. Converting complex HTML (navigation, ads, scripts) into accurate plain text is hard and often lossy.

Providing concise, expert-grade information in a single accessible place improves accuracy—especially for developer documentation and API references.

How to use

For AI assistants / LLMs

1. Start with llms-index.json (entry points, reading order, v8-by-default policy, and the english block for English llms URLs):

https://pro.autojs.run/docs/llms-index.json

2. Recommended for English: llms-en.txt (overview and TOC for the English doc set, v8 scope):

https://pro.autojs.run/docs/llms-en.txt

3. llms-en-full.txt (full plain-text bundle for the English doc set, v8 scope):

https://pro.autojs.run/docs/llms-en-full.txt

4. English v9 only when needed:

https://pro.autojs.run/docs/llms-en-v9.txt
https://pro.autojs.run/docs/llms-en-v9-full.txt

5. Chinese docs (optional) — if you need the Chinese site instead, use the default files (same hostname, zh-CN paths in the index):

https://pro.autojs.run/docs/llms.txt
https://pro.autojs.run/docs/llms-full.txt
https://pro.autojs.run/docs/llms-v9.txt
https://pro.autojs.run/docs/llms-v9-full.txt

6. Skill files (optional) — for English workflows, prefer:

• https://pro.autojs.run/docs/skills/autojspro-docs-llms/SKILL.en.md
• https://pro.autojs.run/docs/skills/autojspro-docs-llms/QUICKSTART.md

Chinese-oriented skills (same v8-first rules):

• https://pro.autojs.run/docs/skills/autojspro-docs-llms/SKILL.md
• https://pro.autojs.run/docs/skills/autojspro-docs-llms/QUICKSTART.zh.md

For developers

When using an AI assistant, prefer the English llms for English answers:

• Index: https://pro.autojs.run/docs/llms-index.json
• v8 (English): https://pro.autojs.run/docs/llms-en.txt, https://pro.autojs.run/docs/llms-en-full.txt
• Quickstart (English): https://pro.autojs.run/docs/en/guide/quickstart.html

And instruct explicitly:

Default to v8. Use llms-en-v9.txt / llms-en-v9-full.txt only for migration or when the user explicitly asks for v9.

Sample prompt (English):

Answer in English using Auto.js Pro docs. Start from:
- https://pro.autojs.run/docs/llms-index.json (see "english" for entry URLs)
- https://pro.autojs.run/docs/llms-en.txt
- https://pro.autojs.run/docs/llms-en-full.txt

Default to API v8. Use v9 English bundles only for migration or explicit v9 requests:
- https://pro.autojs.run/docs/llms-en-v9.txt
- https://pro.autojs.run/docs/llms-en-v9-full.txt

Related links

• VuePress LLM plugin
• llms.txt specification

You can create a new project on the home page. Multiple project templates are available (Pro 8.7+).

project.json

project.json configures project parameters, such as entry file, splash screen, package name, and more.

| Field | Meaning | Type | Default |
|

Download and install Auto.js Pro from the official website: https://wwwq.lanzouc.com/b02wvkxpe.

Auto.js Pro supports Android 5.0+ devices (including emulators). Due to app hardening, it may not start on devices with Xposed frameworks installed.

After launching the app, register an account. Purchase a lifetime membership in the app to unlock full features.

Write your first line of code

On the home screen, grant file permissions, then tap the floating menu button at the bottom-left and choose Files.

Enter the file name “First line of code” and confirm.

Auto.js will open the editor. Enter:

toastLog("Hello, Auto.js");

Tap Run (top-right). Auto.js will show a toast message and print a log entry.

You have now written and run your first script. Auto.js Pro can be used to build tools and small apps, and can also package code into a standalone APK.

Learn JavaScript

The js in Auto.js stands for JavaScript. JavaScript is widely used across web frontend, Node.js backend, and desktop development.

If you are new to programming, it is strongly recommended to learn JavaScript first. Some recommended resources:

• Video: Mosh JavaScript tutorial (Chinese)
• Text: MDN JavaScript

Choose a JavaScript engine

Auto.js Pro currently supports two engines:

• Rhino 1.7.14: ES5 + partial ES6. Used by Free and legacy Pro. The APIs based on it are often called v8 / API v1.
• V8: In Pro 9, Auto.js Pro adds a Node.js 16.x engine. APIs based on it are often called v9 / API v2.

If you are a beginner, start with Rhino + v8 first, then move to Node.js + v9 later.

If you want to learn the differences, see the v9 documentation.

This documentation site (and default AI retrieval) recommends using v8 by default. v9 currently has a memory leak risk and is not recommended as the default option unless you are migrating or explicitly need Node.js features.

What can Auto.js Pro do?

Build a small app using JavaScript (and Node.js in Pro 9).

Build small apps

Auto.js Pro can build complete applications, and package a JavaScript project into a standalone APK. You can build UI with web technologies, use Auto.js widgets for simple UIs, or even build polished interfaces with native Android resources.

You can also install npm packages, load dex/jar/native libraries, and connect the Android + Node.js ecosystems. Many projects go beyond “scripts”, such as small games or HTTP servers.

Learn JavaScript and validate ideas

Auto.js Pro includes professional tools like a multi-tab editor and debugger, and you can also use VSCode to write and run code. It works well as a learning tool for beginners, a low-barrier entry into development, and a fast playground for experienced developers to validate ideas.

Advantages compared to other versions

• Node.js engine

  Pro 9 adds Node.js 16.x, with 100×+ performance and ES2021 support.

• Plugin store & no separate install

  Plugins can be merged into the APK when packaging.

• Stronger encryption

  Node.js engine encryption is significantly harder to reverse.

• Great VSCode debugging

  Remote step debugging, auto-completion, faster file sync, and device file management.

• NPM ecosystem

  Install and use packages like ws/express/koa.

• Code store

  Download and share projects and scripts.

• Packaging customization

  Customize signature/ABI/splash/permissions, optimize size, and obfuscate components.

• React/Vue/Web UI

  Official support for web-based UIs and Web interaction APIs.

• Multi-tab workspace

  File tree management, LSP completion, and diagnostics.

• Visual UI designer

  Visual UI design for easier UI building.

• More APIs

  WebSocket, database, native UI, tasks, settings, OCR, etc.

Learning path overview

Auto.js Pro uses JavaScript as its scripting language. There are two JavaScript engines:

• Rhino 1.7.14: ES5 + partial ES6. Used by Free and legacy Pro. The APIs based on it are often called v8 / API v1 in this documentation.
• Chrome V8: In Pro 9, Auto.js Pro adds a Node.js 16.x engine. APIs based on it are often called v9 / API v2.

Before learning Auto.js Pro, it is strongly recommended to learn JavaScript basics.

Also, the built-in examples are very important. Running examples for each module is one of the fastest ways to understand the platform.

What Auto.js Pro must NOT be used for

Even though Auto.js Pro is powerful, it must not be used for illegal or abusive purposes (e.g. game cheating, reading/writing other apps’ memory, or other black/gray industry use cases).

How to get Auto.js Pro

Download the Android app from the Download page.

Then you can start with your first line of code.

• See also: API v2 vs API v1

Note: The current API v2 (v9) may have memory leak risks. Unless you explicitly need to migrate, verify compatibility, or use Node.js features, you may want to continue prioritizing API v1 (v8) for production scripts.

Enable the second generation API with Node.js engine

For compatibility, Auto.js Pro 9 still defaults to the old Rhino engine (API v1). To use API v2, you must run the script on the Node.js engine.

• See: Run code with the Node.js engine

From globals to require()

In API v2, every module must be imported (for example with require). In API v1, APIs such as app and image lived on globals; in v2 you pull them in explicitly, for example:

// API v1
app.viewFile(...)

// API v2
const app = require('app');
app.viewFile(...)

// Or import only what you need
const { viewFile } = require('app');
viewFile(...)

Most first-generation globals are not available directly, for example sleep, log, and toast:

// API v1
sleep(1000);
log(context.getPackageName());
toast("");

// API v2
const { delay } = require("lang");
const { showToast } = require("toast");

async function main() {
  await delay(1000);
  const context = $autojs.androidContext;
  console.log(context.getPackageName());
  showToast("Hello");
}
main();

Module and function controls

In API v2, some module names are similar to v1 (for example app, color); some features moved to other modules; some v1 modules are replaced by Node.js built-ins (for example files → fs / path); and some are better covered by npm packages (for example WebSocket → the ws package).

Below is a quick map from common v1 modules to v2. Even when names look similar, APIs may differ (for example v1 device.width vs v2 device.screenWidth—check the device docs for exact names).

• app

Use the app module.

• base64

Use Node.js Buffer instead. For example:

• To Base64: Buffer.from("autojs", "utf8").toString("base64")

• From Base64: Buffer.from("YXV0b2pz", "base64").toString("utf8")

• color

Use the color module.

• canvas

The canvas module is similar to the old version. Canvas is currently not supported inside the v9 UI module.

• console

console.log can be used directly. See Console.

Replace print() / log() with console.log(). For example, replace log("hello") with console.log("hello").

• crypto

Use the Node.js crypto module.

• debug

No direct replacement is provided in API v2.

• device

Use the device module.

• dialogs

Use the dialogs module.

• engines

Use the engines module.

• events

In API v2, some of the old events map to Node.js process events. For example:

1. exit → process.on("exit", () => {})

• floating_window

Use the floating_window module.

• files

Use Node.js fs and path.

• global functions and variables

• sleep → delay from lang, e.g. await delay(1000)

• toast / toastLog → showToast from toast, e.g. showToast("hello", { log: true })

• exit → process.exit()

• random → Math.random() (if you need an integer range, you can implement a helper):

  "nodejs";
  function random(min, max) {
    min = Math.ceil(min);
    max = Math.floor(max);
    return Math.floor(Math.random() * (max - min + 1)) + min;
  }
  console.log(random(10, 30));

• requiresApi → requiresAndroidVersion on OS (see device)

• requiresAutojsVersion → check process.versions.autojspro

• runtime.requestPermissions → this.requestPermissions on an Activity instance

• runtime.loadJar / runtime.loadDex → $java.loadJar / $java.loadDex (see $java.loadDex)

• context → $autojs.androidContext

• http

Recommended: use the built-in axios module, which is more capable than the legacy HTTP helpers.

• media

Use the media module.

• plugins

Use the plugins module.

• power_manager

Use the power_manager module.

• sensors

Use the sensors module.

• shell

Use the shell module.

• storages

Use the datastore module.

• settings

Use the settings module.

• threads

See: Multithreading and async (below).

• Timers

Use Node’s timers module. In practice setTimeout and setInterval are available as globals in the v2 runtime as well.

• work_manager

Use the work_manager module.

• ui

Use the ui module. UI APIs differ a lot from v1; see UI migration below and Threads and UI in the v9 README.

• util

Use Node.js util.

• WebSocket

Prefer the npm ws package instead of the old built-in WebSocket helper.

• zip

Use the zip module.

Async and Promises

Understanding async/await and Promises is essential for v2: most I/O and Android-facing helpers return Promises instead of blocking the script thread like many v1 APIs did.

• Use an async function as your script entry (for example main()), await any API that returns a Promise, and attach .catch(...) on the top-level promise so rejections are not silent.
• Concurrency is not the same as parallel threads: await yields control back to the runtime; overlapping work is scheduled by the engine. For Java calls from JS, use thread hints on .invoke(...) (for example "ui" vs "io") as documented there.
• For a broader mental model (event loop, timers, process.nextTick), follow any up-to-date Node.js or JavaScript async guide alongside this doc.

UI migration

The v2 UI stack (require("ui"), XML activities, JsWebView, and related modules) differs a lot from v1. Start from the English v9 README sections Threads and UI and UI entry headers, then read the ui barrel and submodules (ui/activity, ui/layout, ui/web, …).

Multithreading and async

v2 follows Node’s single-threaded JavaScript model: your code runs on one JS thread, while heavy or platform work runs on native/runtime threads behind Promise-based APIs. Prefer async composition over blocking sleeps; use worker threads or split processes only when you truly need parallel JS (advanced). See also Threads and UI in the v9 README.

This site documents the v9 (Node.js) API. For the legacy API, switch the documentation tree to v8.

The v9 runtime can still exhibit memory leaks in some patterns. Do not treat it as the default choice for new scripts or for AI-generated samples unless you explicitly need Node/npm—or you are migrating or comparing behavior. For day-to-day automation, prefer the first-generation (Rhino) API unless you know you need v9.

Second-generation vs first-generation

Advantages of Node.js (v9) over Rhino (v8):

• JavaScript execution is orders of magnitude faster than Rhino.
• Scripts packaged with the Node engine get stronger protection; reversing is not practical today.
• Modern ES2021+ language features; Rhino stays near ES5 plus a subset of ES6.
• Fewer engine-level surprises; Rhino’s module system and edge cases have historically been painful.
• The v9 API surface is cleaner and closer to platform norms.
• require("npm-package") works for supported dependencies.
• More learning material exists on the open web for Node than for Rhino-in-Auto.js.

Disadvantages:

• Higher learning curve—Promises, async flows, and tooling matter, especially for beginners.
• Generated docs are dense; they follow TypeScript typings, so naming and edge-case notes can still evolve.
• The v8 / Rhino community still has more scripts, snippets, and Q&A in Chinese forums.
• v8 feels “batteries included” for small linear automations.

Choosing an engine when you start out

Prefer Rhino + v8 if you:

1. Have little programming background and do not plan to go deep.
2. Only need scripts that “run once” without caring about structure.
3. Can live with older syntax and occasional engine quirks.

No extra header is required—Rhino remains the default in Pro 9.

Prefer Node + v9 if you:

1. Already develop software or are comfortable reading modern JS.
2. Want industry-standard patterns (async/await, modules, npm) as a foundation for Android / JS / Web later.
3. Care about maintainability and structure.
4. Need stronger packaging / obfuscation for shipped scripts.
5. Want npm for databases, protocols, parsers, etc.
6. Need maximum JS throughput.
7. Enjoy experimenting with new stacks.

You can still skim v8 docs—most concepts (intents, selectors, UI) transfer.

Quick start: run on the Node engine

For compatibility, files still run on Rhino unless you opt into Node. Either:

1. Put "nodejs"; on the first line of the script:

"nodejs";

console.log(`Node.js version: ${process.version}`);

2. Name the file *.node.js or *.mjs (.mjs also enables ES modules per Node rules).

Node.js built-in modules

You get the usual Node built-ins, for example:

• fs — filesystem (similar idea to Pro 8’s files module).
• http / https — clients and small servers.
• worker_threads — parallel JS (rough analogue to Pro 8 threads).
• path, crypto, buffer, … — see the official index.

Full reference: Node.js 16.x docs (the version bundled with Pro 9).

Example — read a text file with fs:

"nodejs";

const fs = require("fs");

// https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsreadfilepath-options-callback
fs.readFile("/sdcard/scripts/test.txt", { encoding: "utf-8" }, (err, data) => {
  if (err) {
    console.error("Read file failed:", err);
  } else {
    console.log("Read file success:", data);
  }
});

Pro 9 built-in modules

Node covers general-purpose APIs; Pro 9 still ships Android-centric modules, for example:

• app — intents, other packages, broadcasts, email, etc.
• ui — layouts, activities, WebView-backed screens.
• accessibility — UI automation through the accessibility tree.
• image, media_projection, dialogs, … — browse the sidebar.

Every Pro 9 module must be require’d. Globals such as bare app / $app from Pro 8 are gone—use const app = require("app");.

Most v9 calls are async (Promise) instead of blocking the JS thread the way v8 often did. Example: requestScreenCapture in v8 blocked until the user answered; in v9 it returns a Promise—use await / .then(). Clipboard helpers moved from globals into clip_manager (setClip / getClip).

Example — screenshot + template match:

const { readImage, findImage } = require("image");
const { requestScreenCapture } = require("media_projection");

async function main() {
  const capturer = await requestScreenCapture();
  const template = await readImage("./template.png");
  const capture = await capturer.nextImage();
  const result = await findImage(capture, template);
  console.log("findImage: ", result);
  capturer.stop();
  template.recycle();
}

main();

Install npm packages into a project

1. Create a Node.js project from the file manager template (bottom-right menu → Project).
2. Fill in the app label and a real application id containing a dot, e.g. com.example.
3. Open the project toolbar → Terminal.
4. Run npm i --no-bin-links <package> (installs into node_modules).
5. Import with require("package") (or import inside .mjs).

"nodejs";
const uuid = require("uuid");
console.log("uuid:", uuid.v4());

Use cd into the project folder before installing additional packages.

--no-bin-links avoids symlinked .bin shims—FAT/SD storage on Android often cannot create symlinks. Call CLI entrypoints via node node_modules/<pkg>/bin/...js instead, or move scripts to an app-private directory whose filesystem supports links (understand that uninstall wipes that storage).

Global npm tools

You can still npm i -g typescript and run tsc from the built-in terminal, bundle with webpack-cli, etc.

Do not upgrade the embedded npm—support assumes the shipped version. Global installs must omit --no-bin-links, otherwise shell shims will not register.

Calling Java / Android APIs

$autojs exposes helpers such as $autojs.java:

"nodejs";
const $java = $autojs.java;
const StringBuilder = $java.findClass("java.lang.StringBuilder");
const sb = new StringBuilder();
sb.append("Hello");
sb.append(2);
console.log(sb.toString());

See globals / $java docs for thread modes, wrap, create, etc.

For a Pro-8–style java.* / android.* surface, call:

"nodejs";
require("rhino").install();

const StringBuilder = java.lang.StringBuilder;
const sb = new StringBuilder();
sb.append(android.util.Base64.decode("YXV0b2pz", 0));
console.log(sb.toString());

importClass / importPackage / JavaAdapter are not supported in this mode yet.

Threads and UI

Single-threaded Node model

Pro 9 follows Node’s single-threaded event loop—you cannot spawn Rhino-style threads workers.

Heavy work (findImage, gestures, I/O) is exposed as async APIs so multiple operations can overlap. For Java calls, pass a thread hint such as "io" or "ui" on .invoke(...) (see globals Java).

For CPU-bound pure JS in parallel, use worker_threads (consult Node docs). Workers do not see $autojs, Auto.js modules, or Android APIs—only Node built-ins.

UI entry headers

Prefix the first line with "nodejs ui" or "nodejs ui-thread" when you must touch widgets on the main thread:

"nodejs ui";
const { isUiThread } = require("ui");
console.log(isUiThread());

• ui — you are building a visible Activity / layout flow (see the UI module).
• ui-thread — no extra Activity, but code runs on the UI thread (typical for floating windows).

For one-off UI work from a background script, marshal to "ui" via Java .invoke(..., "ui") (e.g. view.setText.invoke(view, ["hello"], "ui")).

How to read generated module docs

Docs are generated from TypeScript typings—knowing the layout helps.

Open app, for example. Sections mean:

• Interfaces — skip on first pass unless you need field-level detail.
• Variables — exported singletons/constants (packageName, …).

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

packageName is marked const (string)—assigning to it throws; the name tells you it is the current package id.

• Functions — e.g. editFile, startActivity. Signatures look like:

startActivity(target: string | IntentOptionsWithRoot): Promise<void>

string shortcuts mirror Pro 8 ("console", "settings", …). For objects, open IntentOptionsWithRoot—note root?: boolean and inheritance from IntentOptions. Toggle Inherited in the type viewer to see merged fields (action, data, flags, …).

Putting it together:

"nodejs";
const app = require("app");
app.startActivity({
  root: false,
  action: "android.intent.action.VIEW",
  data: "https://pro.autojs.org",
});

The Auto.js Advanced Edition is a “revived” build based on Auto.js Pro 9.3.11 after the official service shutdown. It fixes server APIs, provides self-hosted optimizations, keeps feature parity with the official Pro version, and adds multiple enhancements.

It aims to provide an automation platform that is root-free, host-free (no forwarding configuration), stable for packaging, and efficient at runtime.

🔥 Auto.js Advanced Edition 9.3.11 (All-in-one build)

The optimized local client and server provide these key capabilities:

• 🚫 No Host configuration needed: seamlessly connects to server APIs without complex network setup.
• ✅ Packaging without crashes: customized client to fix “packaged script crash” issues.
• 🌍 Multi-device support: one invitation code can be used across devices; switch flexibly.
• 🚀 One-click install: quick onboarding with a direct installation experience.
• 💻 Remote debugging from PC: connect via VSCode for efficient debugging.
• 📱 WeChat obfuscated widgets support: supports recognition and clicking for the latest WeChat obfuscated controls, including packaged apps.
• ⚙️ Custom accessibility service class name: for packaging scenarios that require adapting to app detection/whitelists.
• 🔄 Auto-start on boot: packaged apps can support auto start on device boot.
• ☁️ Hot update: load JS code, snapshot sources, and zipped projects from network for flexible deployments.

🚀 Quick start

1. Open the app and tap Login.
2. Enter the invitation code to unlock all features.

💬 Get an invitation code

• QQ group: 1065375789
• QQ: 68107808
• WeChat: 68107808

✨ Core features

🔗 Seamless official API compatibility

• 🛠️ Supports all Auto.js native APIs.
• 🔌 Compatible with third-party extensions; supports self-made extensions.
• 📸 Built-in OCR plugins for image recognition needs.

🛡️ Root-free & Host-free forwarding

• 🔧 Source-level optimizations to connect directly in the background.
• 🌐 Built-in traffic forwarding mechanism without Root or Host.
• 📲 Works after installation without extra permission configuration.

🔓 Unlock functional limitations

• ✅ Automatically removes click restrictions of mainstream app controls to improve compatibility.
• 🛠️ Better adaptation to complex UIs to improve automation success rate.

🔒 Encryption & security

• 🔐 Enhanced offline encryption to protect script logic.
• 📷 Snapshot encryption to secure core code.
• 🛡️ Reduces risk of logic leakage and protects developer interests.

🔄 One code for multiple devices

• 📱 One invitation code supports switching among multiple devices.
• ⚠️ Note: Using across different IPs may cause account kick-out; plan usage reasonably.

⚙️ Highlights

1. Deep optimizations based on Auto.js Pro 9.3.11:
   • Full functionality; stable packaging without crashing.
   • No Host configuration; install and use immediately.
2. Adaptation for the latest WeChat obfuscated widgets:
   • More accurate recognition/clicking to improve success rate.
3. Support packaged apps to start on boot

Tip: Uninstall the old version and install this advanced build for changes to take effect.

4. VSCode remote debugging:
   • Remote-connect VSCode from PC to debug scripts in real time.
   • VSCode debugging tutorial
5. Custom accessibility service class name:
   • Packaging supports custom service class names to adapt to specific app detection mechanisms.
6. Hot update:
   • Load JS/snapshots/zipped projects from network to implement hot updates flexibly.

🌐 Run remote code resources

See: Run remote script resources

Copyright & notice

All resources are collected from the Internet. Copyright belongs to the original authors. If there is any infringement or other issue, please contact the maintainers for timely handling.

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);

$base64.encode(str, encoding = 'utf-8')

[Added in Pro 7.0.4]

• str {string} String to encode
• encoding {string} Optional character encoding

Encodes str with Base64 and returns the encoded string.

console.log($base64.encode("test")); // prints dGVzdA==

$base64.decode(str, encoding = 'utf-8')

[Added in Pro 7.0.4]

• str {string} Base64 string to decode
• encoding {string} Optional character encoding

Decodes Base64 string str and returns the decoded string.

console.log($base64.decode("dGVzdA==")); // prints test

The canvas coordinate system is a 2D Cartesian coordinate system. The origin is at the top-left corner of the view; the X axis points right along the top edge, and the Y axis points down along the left edge. For example, on a 1920×1080 screen where the canvas view covers the whole screen, draw a line from top-left to bottom-right:

canvas.drawLine(0, 0, 1080, 1920, paint);

Canvas drawing relies on a Paint. By setting stroke width, color, fill style, etc., you can change how shapes are rendered. Example: draw a solid red square:

let paint = new Paint();
// Fill style: shapes are solid
paint.setStyle(Paint.Style.FILL);
// Red color
paint.setColor(colors.RED);
// Draw a square from (0, 0) to (100, 100)
canvas.drawRect(0, 0, 100, 100, paint);

To draw only the square outline, set the paint style to stroke:

let paint = new Paint();
// Stroke style: shapes are outlines
paint.setStyle(Paint.Style.STROKE);
// Red color
paint.setColor(colors.RED);
// Draw a square from (0, 0) to (100, 100)
canvas.drawRect(0, 0, 100, 100, paint);

With Paint, canvas can draw basic shapes, images, and more.

Common Methods Index

Draw colors:

• Draw by R,G,B: canvas.drawRGB(r, g, b)
• Draw by A,R,G,B: canvas.drawARGB(r, g, b)
• Draw with a color value: canvas.drawColor(color)
• Draw with a color and blend mode: canvas.drawColor(color, mode)

Draw paint:

• canvas.drawPaint(paint)

Draw shapes:

• Draw a point: canvas.drawPoint(x, y, paint)
• Draw multiple points: canvas.drawPoints(pts, paint)
• Draw a line: canvas.drawLine(startX, startY, stopX, stopY, paint)
• Draw multiple lines: canvas.drawLines(pts, paint)
• Draw a rectangle: canvas.drawRect(r, paint)
• Draw an oval: canvas.drawOval(oval, paint)
• Draw a circle: canvas.drawCircle(cx, cy, radius, paint)
• Draw an arc: canvas.drawArc(oval, startAngle, sweepAngle, useCenter, paint)
• Draw a round rect: canvas.drawRoundRect(rect, rx, ry, paint)
• Draw a path: canvas.drawPath(path, paint)

Draw text:

• Draw text on a line: canvas.drawText(text, x, y, paint)
• Draw text on a path: canvas.drawTextOnPath(text, path, hOffset, vOffset, paint)

Draw images:

• Draw a bitmap: canvas.drawBitmap(bitmap, left, top, paint)
• Draw a picture: canvas.drawPicture(picture)

Canvas size:

• Get width: canvas.getWidth()
• Get height: canvas.getHeight()

Transforms:

• Translate: canvas.translate(dx, dy)
• Scale: canvas.scale(sx, sy[, px, py])
• Rotate: canvas.rotate(degrees[, px, py])
• Skew: canvas.skew(sx, sy)

canvas.getWidth()

• Returns {number}

Returns the width of the current canvas layer.

canvas.getHeight()

• Returns {number}

Returns the height of the current canvas layer.

canvas.drawRGB(r, g, b)

• r {number} Red channel value
• g {number} Green channel value
• b {number} Blue channel value

Fill the entire drawable area with the color specified by r, g, b. Equivalent to canvas.drawColor(colors.rgb(r, g, b)).

canvas.drawARGB(a, r, g, b)

• a {number} Alpha channel value
• r {number} Red channel value
• g {number} Green channel value
• b {number} Blue channel value

Fill the entire drawable area with the color specified by a, r, g, b. Equivalent to canvas.drawColor(colors.argb(a, r, g, b)).

canvas.drawColor(color)

• color {number} Color value

Fill the entire drawable area with the color specified by color.

canvas.drawColor(color, mode)

• color {number} Color value
• mode {PorterDuff.Mode} Blend mode

Fill the entire drawable area with color using the blend mode.

canvas.drawPaint(paint)

• paint {Paint} Paint

Fill the entire drawable area with the specified paint. This is equivalent to drawing an infinitely large rectangle, but faster. You can use this to draw patterns using a shader.

canvas.drawPoint(x, y, paint)

• x {number} X coordinate
• y {number} Y coordinate
• paint {Paint} Paint

Draw a point at (x, y) in the drawable area.

The point shape is determined by the paint stroke cap (see paint.setStrokeCap(cap)). The point size is determined by the paint stroke width (see paint.setStrokeWidth(width)).

If the paint stroke width is 0, it still draws 1 pixel (up to 4 pixels if anti-aliasing is enabled).

Equivalent to canvas.drawPoints([x, y], paint).

canvas.drawPoints(pts, paint)

• pts {number[]} Point coordinate array: [x0, y0, x1, y1, x2, y2, ...]
• paint {Paint} Paint

Draw multiple points specified by the coordinate array.

canvas.drawLine(startX, startY, stopX, stopY, paint)

• startX {number} Start X
• startY {number} Start Y
• endX {number} End X
• endY {number} End Y
• paint {Paint} Paint

Draw a line from (startX, startY) to (endX, endY). The paint Style is ignored when drawing lines. That is, even if the style is set to “FILL”, a line is still drawn.

A line that degenerates into a point (length 0) will not be drawn.

canvas.drawLines(pts, paint)

• pts {number[]} Point coordinate array: [x0, y0, x1, y1, x2, y2, ...]
• paint {Paint} Paint

Draw a series of lines by connecting points in pairs from the coordinate array.

Each line uses 4 consecutive values in the array, so to draw one line the array must contain at least 4 values. Equivalent to canvas.drawLine(pts[0], pts[1], pts[2], pts[3], paint) then canvas.drawLine(pts[4], pts[5], pts[6], pts[7], paint), and so on.

The paint Style is ignored when drawing lines. That is, even if the style is set to “FILL”, lines are still drawn.

canvas.drawRect(r, paint)

• r {Rect|RectF} Rectangle bounds
• paint {Paint} Paint

Draw a rectangle specified by bounds r. The paint Style determines whether the rectangle is stroked, filled, or both.

Equivalent to canvas.drawRect(r.left, r.top, r.right, r.bottom, paint).

canvas.drawRect(left, top, right, bottom, paint)

• left {number} Left X
• top {number} Top Y
• right {number} Right X
• bottom {number} Bottom Y
• paint {Paint} Paint

Draw a rectangle defined by (left, top) - (right, bottom). The paint Style determines whether the rectangle is stroked, filled, or both.

canvas.drawOval(oval, paint)

• oval {RectF} Bounds of the oval's bounding rectangle
• paint {Paint} Paint

Draw an oval specified by bounds oval. The paint Style determines whether the oval is stroked, filled, or both.

Equivalent to canvas.drawOval(oval.left, oval.top, oval.right, oval.bottom, paint).

canvas.drawOval(left, top, right, bottom, paint)

• left {number} Left X of the oval bounds
• top {number} Top Y of the oval bounds
• right {number} Right X of the oval bounds
• bottom {number} Bottom Y of the oval bounds
• paint {Paint} Paint

Draw an oval defined by (left, top) - (right, bottom). The paint Style determines whether the oval is stroked, filled, or both.

canvas.drawCircle(cx, cy, radius, paint)

• cx {number} Center X
• cy {number} Center Y
• radius {number} Radius
• paint {Paint} Paint

Draw a circle with center (cx, cy) and radius radius. If radius is less than or equal to 0, nothing is drawn. The paint Style determines whether the circle is stroked, filled, or both.

canvas.drawArc(oval, startAngle, sweepAngle, useCenter, paint)

• oval {RectF} Bounds of the oval used for the arc
• startAngle {number} Start angle (degrees)
• sweepAngle {number} Sweep angle (clockwise, degrees)
• useCenter {boolean} Whether to connect the arc to the oval center
• paint {Paint} Paint

Draw an arc in the drawable area. The arc is a part of the oval specified by oval, starting at startAngle and sweeping clockwise by sweepAngle.

If startAngle is negative or (\ge 360), it is taken modulo 360. Arcs are drawn clockwise. A start angle of 0° corresponds to the 3 o'clock direction.

If sweepAngle is (\ge 360), this draws a full oval. Note this differs from path.arcTo, which takes the sweep modulo 360. If sweepAngle is negative, it is taken modulo 360.

If useCenter is true, the arc will be connected to the oval center when stroking/filling, producing a sector.

Equivalent to canvas.drawArc(oval.left, oval.top, oval.right, oval.bottom, startAngle, sweepAngle, useCenter, paint).

canvas.drawArc(left, top, right, bottom, startAngle, sweepAngle, useCenter, paint)

• left {number} Left X of the oval bounds
• top {number} Top Y of the oval bounds
• right {number} Right X of the oval bounds
• bottom {number} Bottom Y of the oval bounds
• startAngle {number} Start angle (degrees)
• sweepAngle {number} Sweep angle (clockwise, degrees)
• useCenter {boolean} Whether to connect the arc to the oval center
• paint {Paint} Paint

Draw an arc in the drawable area using the oval bounds (left, top) - (right, bottom). For details, see canvas.drawArc(oval, startAngle, sweepAngle, useCenter, paint).

canvas.drawRoundRect(rect, rx, ry, paint)

• rect {RectF} Rectangle bounds
• rx {number} X radius for corners
• ry {number} Y radius for corners
• paint {Paint} Paint

Draw a round-rect specified by bounds rect and corner radii rx, ry. The paint Style determines whether it is stroked, filled, or both.

Equivalent to canvas.drawRoundRect(rect.left, rect.top, rect.right, rect.bottom, rx, ry, paint).

canvas.drawRoundRect(left, top, right, bottom, rx, ry, paint)

• left {number} Left X
• top {number} Top Y
• right {number} Right X
• bottom {number} Bottom Y
• rx {number} X radius for corners
• ry {number} Y radius for corners
• paint {Paint} Paint

Draw a round-rect defined by (left, top) - (right, bottom) with corner radii rx, ry. The paint Style determines whether it is stroked, filled, or both.

canvas.drawPath(path, paint)

• path {Path} Path
• paint {Paint} Paint

Draw the specified path. The paint Style determines whether the path is stroked, filled, or both.

canvas.drawBitmap(bitmap, left, top, paint)

• bitmap {Bitmap} Bitmap
• left {number} X coordinate
• top {number} Y coordinate
• paint {Paint} Paint

Draw the specified bitmap so its top-left corner is at (left, top), applying the canvas transform matrix.

If the bitmap density differs from the canvas density, the bitmap will be scaled to match the canvas density before drawing.

canvas.drawPicture(picture)

• picture {Picture} Picture

Save the canvas transform and clip bounds, draw the picture, then restore them. This differs from picture.draw(canvas), which does not save/restore automatically.

canvas.drawText(text, x, y, paint)

• text {string} Text
• x {number} X coordinate
• y {number} Y coordinate
• paint {Paint} Paint

Draw text in the drawable area so the text origin is at (x, y). The start position depends on the paint alignment options. Text style depends on paint settings.

canvas.drawTextOnPath(text, path, hOffset, vOffset, paint)

• text {string} Text
• path {Path} Path
• hOffset {number} Offset parallel to the path (positive moves along the path direction)
• vOffset {number} Offset perpendicular to the path (positive moves downward relative to the text)
• paint {Paint} Paint

Draw text along the specified path. The start position depends on paint alignment options. Text style depends on paint settings.

canvas.translate(dx, dy)

• dx {number} Translation along +X (negative means opposite direction)
• dy {number} Translation along +Y (negative means opposite direction)

Right-multiply the current transform matrix by a translation matrix, effectively translating the coordinate system.

canvas.scale(sx, sy[, px, py])

• sx {number} Scale factor on X (negative flips along X)
• sy {number} Scale factor on Y (negative flips along Y)
• px {number} Pivot X, default 0
• py {number} Pivot Y, default 0

Right-multiply the current transform matrix by a scaling matrix. This scales the coordinate system around (px, py). A factor > 1 zooms in; < 1 zooms out.

canvas.rotate(degrees[, px, py])

• degrees {number} Rotation angle (degrees)
• px {number} Pivot X, default 0
• py {number} Pivot Y, default 0

Right-multiply the current transform matrix by a rotation matrix, effectively rotating the coordinate system around (px, py) by the specified angle.

canvas.skew(sx, sy)

• sx {number} Skew factor along X axis
• sy {number} Skew factor along Y axis

Right-multiply the current transform matrix by a skew matrix.

Stability: 2 - Stable

In Auto.js, there are two ways to represent a color.

One way is a string "#AARRGGBB" or "#RRGGBB", where:

• AA is the alpha channel (opacity)
• RR is red
• GG is green
• BB is blue

For example, "#ffffff" means white, and "#7F000000" means semi-transparent black.

Another way is a hexadecimal 32-bit integer 0xAARRGGBB, for example:

• 0xFF112233 represents "#112233"
• 0x11223344 represents "#11223344"

You can convert a color integer to a string with colors.toString(), and parse a color string into an integer with colors.parseColor().

colors.toString(color)

• color {number} Color integer
• Returns {string}

Returns the color as a string in the "#AARRGGBB" format.

colors.red(color)

• color {number | string} Color value
• Returns {number}

Returns the red channel value of color, range 0 ~ 255.

colors.green(color)

• color {number | string} Color value
• Returns {number}

Returns the green channel value of color, range 0 ~ 255.

colors.blue(color)

• color {number | string} Color value
• Returns {number}

Returns the blue channel value of color, range 0 ~ 255.

colors.alpha(color)

• color {number | string} Color value
• Returns {number}

Returns the alpha channel value of color, range 0 ~ 255.

colors.rgb(red, green, blue)

• red {number} Red channel value
• blue {number} Green channel value
• green {number} Blue channel value
• Returns {number}

Returns the integer color composed by these channels. Alpha is fixed to 255 (opaque).

colors.argb(alpha, red, green, blue)

• alpha {number} Alpha channel value
• red {number} Red channel value
• green {number} Green channel value
• blue {number} Blue channel value
• Returns {number}

Returns the integer color composed by these channels.

colors.parseColor(colorStr)

• colorStr {string} Color string, e.g. "#112233"
• Returns {number}

Returns the color as an integer value.

colors.BLACK

Black, value #FF000000.

colors.DKGRAY

Dark gray, value #FF444444.

colors.GRAY

Gray, value #FF888888.

colors.LTGRAY

Light gray, value #FFCCCCCC.

colors.WHITE

White, value #FFFFFFFF.

colors.RED

Red, value #FFFF0000.

colors.GREEN

Green, value #FF00FF00.

colors.BLUE

Blue, value #FF0000FF.

colors.YELLOW

Yellow, value #FFFFFF00.

colors.CYAN

Cyan, value #FF00FFFF.

colors.MAGENTA

Magenta, value #FFFF00FF.

colors.TRANSPARENT

Transparent, value #00000000.

Stability: 2 - Stable

The console module provides a debugging console similar to those in web browsers. It is used to output debug information, intermediate results, etc. Some functions in this module can also be used as global functions, such as log and print.

console.show()

Show the console. This displays a floating console window (requires floating window permission).

console.hide()

Hide the floating console window.

console.clear()

Clear the console.

console.log([data][, ...args])#

• data {any}
• ...args {any}

Print to the console with a trailing newline. You can pass multiple arguments: the first is the main message, and the rest are substitution values similar to printf(3) (all arguments are passed to util.format()).

const count = 5;
console.log('count: %d', count);
// Prints: count: 5 to stdout
console.log('count:', count);
// Prints: count: 5 to stdout

See util.format() for details.

This function can also be used as a global function.

console.verbose([data][, ...args])

• data {any}
• ...args {any}

Similar to console.log, but the output is shown in gray. Lower priority than log, suitable for informational output.

console.info([data][, ...args])

• data {any}
• ...args {any}

Similar to console.log, but the output is shown in green. Higher priority than log, suitable for important information.

console.warn([data][, ...args])

• data {any}
• ...args {any}

Similar to console.log, but the output is shown in blue. Higher priority than info, suitable for warnings.

console.error([data][, ...args])

• data {any}
• ...args {any}

Similar to console.log, but the output is shown in red. Higher priority than warn, suitable for errors.

console.assert(value, message)

• value {any} Boolean value to assert
• message {string} Message to output when value is false

Assertion. If value is false, outputs the error message and stops the script.

var a = 1 + 1;
console.assert(a == 2, "Addition failed");

console.time([label])

[Added in v4.1.0]

• label {String} Timer label (optional)

Start a timer to measure how long an operation takes. The timer is identified by a unique label. When calling console.timeEnd(), use the same label to stop the timer and print the duration in milliseconds. Starting a timer with the same label again overwrites the previous one.

console.timeEnd(label)

[Added in v4.1.0]

• label {String} Timer label

Stop a timer previously started with console.time() and print the result. The timer is removed after console.timeEnd(). If no timer with the given label exists, it prints NaNms.

console.time('sum');
var sum = 0;
for(let i = 0; i < 100000; i++){
    sum += i;
}
console.timeEnd('sum');
// Prints: sum: xxx ms

console.trace([data][, ...args])

[Added in v4.1.0]

• data {any}
• ...args {any}

Similar to console.log, but also prints a stack trace (current file, line number, etc.).

console.trace('Show me');
// Prints: (stack trace varies depending on call site)
// Show me
//  at <test>:7

console.input(data[, ...args])

• data {any}
• ...args {any}

Outputs like console.log, then shows an input box in the console and waits for input. After pressing confirm, the input string is evaluated with eval and returned.

On some devices, the input box may not show up. This is a known bug.

Example:

var n = console.input("Enter a number:"); 
// After input 123:
toast(n + 1);
// Shows 124

console.rawInput(data[, ...args])

• data {any}
• ...args {any}

Outputs like console.log, then shows an input box in the console and waits for input. After pressing confirm, the input string is returned directly.

On some devices, the input box may not show up. This is a known bug.

Example:

var n = console.rawInput("Enter a number:"); 
// After input 123:
toast(n + 1);
// Shows 1231

console.setSize(w, h)

• w {number} Width
• h {number} Height

Set console size in pixels.

console.show();
// Set console size to a quarter of the screen
console.setSize(device.width / 2, device.height / 2);

console.setPosition(x, y)

• x {number} X coordinate
• y {number} Y coordinate

Set console position in pixels.

console.show();
console.setPosition(100, 100);

console.setGlobalLogConfig(config)

[Added in v4.1.0]

• config {Object} Log configuration. Options include:

  • file {string} Log file path. Logs will be written to this file.
  • maxFileSize {number} Max file size in bytes. Default 512 * 1024 (512KB)
  • rootLevel {string} Minimum log level to write. Default "ALL". Can be "OFF", "DEBUG", "INFO", "WARN", "ERROR", "FATAL", etc.
  • maxBackupSize {number} Max number of backup log files. Default 5.
  • filePattern {string} Log pattern format. See PatternLayout

Configure log saving path and options. For example, save logs to "/sdcard/1.txt":

console.setGlobalLogConfig({
    "file": "/sdcard/1.txt"
});

Note: this affects logging for all scripts.

print(text)

• text {string} | {Object} Content to print to the console

Equivalent to log(text).

Stability: 2 - Stable

This chapter introduces functions for clicking and swiping using screen coordinates. Some require Android 7.0+; others require root permissions.

To get the coordinates of a position to click, you can enable “Pointer location” in Developer options.

Coordinate-based scripts often have resolution issues. You can use setScreenMetrics() to automatically scale coordinates. This affects all coordinate click/press/swipe functions in this chapter. By specifying the resolution the script was designed for, Auto.js will scale coordinates on other resolutions.

You can also combine widgets with coordinates. Some widgets are not clickable (clickable is false), so you can't click them via .click(). If Android is 7.0+ or the device has root permissions, you can click them like this:

// Get the widget
var widget = id("xxx").findOne();
// Click its center
click(widget.bounds().centerX(), widget.bounds().centerY());
// If using root permissions, use Tap

setScreenMetrics(width, height)

• width {number} Screen width in pixels
• height {number} Screen height in pixels

Set the screen width/height that the script's coordinates are based on. If the device screen size differs at runtime, coordinates are scaled automatically.

For example, on a 1920×1080 device:

setScreenMetrics(1080, 1920);
click(800, 200);
longClick(300, 500);

On other devices, Auto.js will scale the coordinates so the script still works. For example, on a 540×960 screen, click(800, 200) actually clicks at (400, 100).

Touch & gesture simulation on Android 7.0+

Stability: 2 - Stable

Note: the following commands only work on Android 7.0+

click(x, y)

• x {number} X coordinate to click
• y {number} Y coordinate to click

Simulate a click at (x, y) and return whether it succeeded. The script continues only after the click finishes.

In general, a click fails only if the click process (~150ms) is interrupted by other events (e.g. user interaction).

If repeated clicks are too slow, use press() instead.

longClick(x, y)

• x {number} X coordinate to long-press
• y {number} Y coordinate to long-press

Simulate a long-press at (x, y) and return whether it succeeded. The script continues only after the long-press finishes (~600ms).

In general, a long-press fails only if it is interrupted (e.g. user interaction).

press(x, y, duration)

• x {number} X coordinate to press
• y {number} Y coordinate to press
• duration {number} Press duration in milliseconds

Simulate pressing at (x, y) and return whether it succeeded. The script continues only after the press finishes.

If the duration is too short, the system treats it as a click. If it exceeds 500ms, it is treated as a long-press.

In general, the operation fails only if it is interrupted.

Example: an auto-clicker loop:

// Loop 100 times
for(var i = 0; i < 100; i++){
  // Press at (500, 1000) for 1ms each time
  press(500, 1000, 1);
}

swipe(x1, y1, x2, y2, duration)

• x1 {number} Start X
• y1 {number} Start Y
• x2 {number} End X
• y2 {number} End Y
• duration {number} Swipe duration in milliseconds

Simulate swiping from (x1, y1) to (x2, y2) and return whether it succeeded. The script continues only after the swipe finishes.

In general, a swipe fails only if it is interrupted.

gesture(duration, [x1, y1], [x2, y2], ...)

• duration {number} Gesture duration
• [x, y] {...} A list of points describing the gesture path

Simulate a gesture. For example, gesture(1000, [0, 0], [500, 500], [500, 1000]) simulates a gesture from (0,0) → (500,500) → (500,1000) with duration 1 second.

gestures([delay1, duration1, [x1, y1], [x2, y2], ...], [delay2, duration2, [x3, y3], [x4, y4], ...], ...)

Simulate multiple gestures at the same time. Each gesture uses parameters [delay, duration, points...], where delay is how long to wait (ms) before starting the gesture, duration is the gesture duration, and points are the path coordinates. The delay parameter can be omitted and defaults to 0.

Example: pinch gesture:

gestures([0, 500, [800, 300], [500, 1000]],
         [0, 500, [300, 1500], [500, 1000]]);

Simple root-based click & swipe commands

Stability: 1 - Experimental

Note: functions in this section may change in future versions. Do not rely heavily on side effects. It is recommended to use RootAutomator instead of these touch functions.

All functions below require root and can click/swipe anywhere.

• These functions usually start with a capital letter to indicate special permissions.
• These functions return no value.
• Their execution is asynchronous and non-blocking, and timing varies by device. The script does not wait for the action to finish before continuing, so it is recommended to add appropriate sleep after each call to achieve the expected effect.

Example:

Tap(100, 100);
sleep(500);

Note that actions may not be stoppable. For example:

for(var i = 0; i < 100; i++){
  Tap(100, 100);
}

After running this code, you may find that clicks continue even after stopping the script in the task manager. Therefore, it is strongly recommended to add a delay after each action:

for(var i = 0; i < 100; i++){
  Tap(100, 100);
  sleep(500);
}

Tap(x, y)

• x {number} X coordinate to tap
• y {number} Y coordinate to tap

Tap (x, y). You can enable “Pointer location” in Developer options to determine coordinates.

Swipe(x1, y1, x2, y2, [duration])

• x1 {number} Start X
• y1 {number} Start Y
• x2 {number} End X
• y2 {number} End Y
• duration {number} Swipe duration

Swipe from (x1, y1) to (x2, y2).

RootAutomator

Stability: 2 - Stable

RootAutomator simulates touch using root permissions. It supports single-touch and multi-touch, and actions are executed without delay.

It is best to have only one RootAutomator instance in a script and ensure it exits when the script ends. You can exit it on the exit event, for example:

var ra = new RootAutomator();
events.on('exit', function(){
  ra.exit();
});
// Perform some tap actions
...

Note

RootAutomator requires root or ADB permissions. To use ADB, set shell.setDefaultOptions({ adb: true }) and authorize Shizuku.

RootAutomator has limited compatibility. Since v9.3, it is recommended to use RootAutomator2 instead.

new RootAutomator([options])

• options {object} Optional:
  • adb {boolean} Whether to use ADB permission. Default false. If true, Shizuku authorization is required.
  • inputDevice {string} Specify the input device used by RootAutomator, e.g. /dev/input/event4. If not set, it will auto-detect.

Create a RootAutomator instance.

RootAutomator.tap(x, y[, id])

• x {number} X coordinate
• y {number} Y coordinate
• id {number} Multi-touch id (optional). Default 1. You can change it via setDefaultId.

Tap at (x, y). id is an integer used for multi-touch; different ids represent different “fingers”. For example:

var ra = new RootAutomator();
// Make "finger 1" tap (100, 100)
ra.tap(100, 100, 1);
// Make "finger 2" tap (200, 200)
ra.tap(200, 200, 2);
ra.exit();

If you don't need multi-touch, omit id. Multi-touch is commonly used for gestures or games, such as simulating two-finger pinch or two-finger swipe.

In some cases, tap may not respond. You can use RootAutomator.press() instead.

RootAutomator.swipe(x1, x2, y1, y2[, duration, id])

• x1 {number} Start X
• y1 {number} Start Y
• x2 {number} End X
• y2 {number} End Y
• duration {number} Swipe duration in milliseconds, default 300
• id {number} Multi-touch id (optional), default 1

Simulate a swipe from (x1, y1) to (x2, y2) that lasts duration milliseconds.

RootAutomator.press(x, y, duration[, id])

• x {number} X coordinate
• y {number} Y coordinate
• duration {number} Press duration
• id {number} Multi-touch id (optional), default 1

Simulate pressing at (x, y) for duration milliseconds.

RootAutomator.longPress(x, y[, id])

• x {number} X coordinate
• y {number} Y coordinate
• duration {number} Press duration
• id {number} Multi-touch id (optional), default 1

Simulate a long-press at (x, y).

The above are basic touch simulation functions. For more complex gestures, use lower-level functions.

RootAutomator.touchDown(x, y[, id])

• x {number} X coordinate
• y {number} Y coordinate
• id {number} Multi-touch id (optional), default 1

Simulate finger down at (x, y).

RootAutomator.touchMove(x, y[, id])

• x {number} X coordinate
• y {number} Y coordinate
• id {number} Multi-touch id (optional), default 1

Simulate moving the finger to (x, y).

RootAutomator.touchUp([id])

• id {number} Multi-touch id (optional), default 1

Simulate lifting the finger.

RootAutomator2

RootAutomator2 simulates taps, gestures, long-presses, etc. using root or ADB permissions. Compared to accessibility-based automation, it supports multi-touch and dynamically changing gestures; compared to RootAutomator, it has better compatibility.

let screenWidth = $device.width;
let screenHeight = $device.height;

// Use root permission. You can also use ADB by specifying { adb: true }, which requires Shizuku authorization
const ra = new RootAutomator2(\{ root: true \});

// Tap at (200, 200)
ra.tap(200, 200);
sleep(1000);

// Press screen center for 500ms
ra.press(screenWidth / 2, screenHeight / 2, 500);
sleep(1000);

// Swipe from (500, 200) to (500, 1000) with duration 300ms
ra.swipe(500, 200, 500, 1000, 300);
sleep(1000);


// Two-finger pinch
// Top-left position
let p0 = {
    x: screenWidth / 6,
    y: screenHeight / 6,
};
// Bottom-right position
let p1 = {
    x: screenWidth - p0.x,
    y: screenHeight - p0.y,
}
// Press down at top-left and bottom-right simultaneously, finger ids 0 and 1
ra.touchDown([
    \{ x: p0.x, y: p0.y, id: 0 \},
    \{ x: p1.x, y: p1.y, id: 1 \},
]);

// Steps
const steps = 20;
// Offset per step
const stepX = Math.round((p1.x - p0.x) / steps) / 2;
const stepY = Math.round((p1.y - p0.y) / steps) / 2;
for (let i = 0; i < steps; i++) {
    // Move finger 0 down-right, finger 1 up-left
    ra.touchMove([
        \{ x: p0.x + stepX * i, y: p0.y + stepY * i, id: 0 \},
        \{ x: p1.x - stepX * i, y: p1.y - stepY * i, id: 1 \}
    ]);
}
// Lift all fingers
ra.touchUp();
// Wait for all operations above to finish
ra.flush();

// Exit RootAutomator2. If you don't exit properly, “fingers” may remain stuck on screen
ra.exit();

new RootAutomator2([options])

• options

  Options for creating RootAutomator2 (optional).

  • adb {boolean} Whether to use ADB permission. Default false.
  • root {boolean} Whether to use root permission. If ADB is not specified, default true.

Create a new RootAutomator2 instance using options. RootAutomator2 has better compatibility than RootAutomator.

You can choose whether to use root or ADB, etc. See ShellOptions. If neither is specified, root is used by default.

RootAutomator2.tap(x, y)

Tap at (x, y) for 5ms. This function waits for the operation to complete synchronously, so execution time may be longer than the actual touch duration. If you need precise timing, use async methods like touchDown / touchUp instead.

Parameters

| Name | Type |
| :

The $crypto module provides symmetric encryption (e.g. AES), asymmetric encryption (e.g. RSA), and message digests (e.g. MD5, SHA).

$crypto.digest(message, algorithm[, options])

• data {any} Data to digest

• key {Key} Digest key (if applicable)

• algorithm {string} Digest algorithm, including:

  • MD5
  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512 (see MessageDigest)

• options {Object} Optional. Specifies the input/output types and formats.

• Returns {any} Return type depends on options.

Computes a digest of data using algorithm. data can be a file, binary, Base64, hex, string, etc. The result can be returned as binary/Base64/hex/string or written to a file, depending on options. See Input/output types and formats.

// MD5 of string "abc"
console.log($crypto.digest("abc", "MD5"));
// SHA-256 of string "abc"
console.log($crypto.digest("abc", "SHA-256"));
console.log($crypto.digest("Auto.js", "SHA-256", \{ input: "string", output: "hex" \}));
// MD5 of file /sdcard/1.txt
console.log($crypto.digest("/sdcard/1.txt", "MD5", {
    input: "file"
}));

$crypto.encrypt(data, key, algorithm[, options])

• data {any} Plaintext. The format depends on options.input.

• key {Key} Encryption key. Symmetric algorithms use one key; asymmetric algorithms use key pairs. See Key.

• algorithm {string} Encryption algorithm, including:

  • AES
  • AES/ECB/NoPadding
  • AES/ECB/PKCS5Padding
  • AES/CBC/NoPadding
  • AES/CBC/PKCS5Padding
  • AES/CFB/NoPadding
  • AES/CFB/PKCS5Padding
  • AES/CTR/NoPadding
  • AES/CTR/PKCS5Padding
  • AES/OFB/PKCS5Padding
  • AES/OFB/PKCS5Padding
  • RSA/ECB/PKCS1Padding
  • RSA/ECB/NoPadding
  • ... (see javax.crypto.Cipher)

• options {Object} Optional. Specifies the input/output types and formats.

• Returns {any} Return type depends on options.

Encrypts data with key key using algorithm. data can be a file, binary, Base64, hex, string, etc. The result can be returned as binary/Base64/hex/string or written to a file, depending on options. See Input/output types and formats.

let message = "Hello Autojs";
// Key: AES requires 128/192/256 bits; here we use 16 chars (= 128 bits)
let str16 = "a".repeat(16);
let key = new $crypto.Key(str16);
// AES
toastLog($crypto.encrypt(message, key, "AES")); // [-18, 27, -69, 81, 2, -87, -116, 23, -114, -86, -111, 40, 58, -127, -29, -59]
// Show AES output in Base64
toastLog(
  $crypto.encrypt(message, key, "AES", {
    output: "base64",
  })
); // 7hu7UQKpjBeOqpEoOoHjxQ==
// AES default padding is PKCS5Padding, so the result is the same
toastLog(
  $crypto.encrypt(message, key, "AES/ECB/PKCS5Padding", {
    output: "base64",
  })
); // 7hu7UQKpjBeOqpEoOoHjxQ==

// AES encrypt
let cipherText = $crypto.encrypt(message, key, "AES");
toastLog(cipherText); // [-18, 27, -69, 81, 2, -87, -116, 23, -114, -86, -111, 40, 58, -127, -29, -59]

// RSA256KeyPair
let algorithm = "RSA";
let length = "2048";
// Generate RSA key pair
key = $crypto.generateKeyPair(algorithm, length);
let message = "Hello Autojs";
// RSA encrypt
cipherText = $crypto.encrypt(message, key.publicKey, "RSA/ECB/PKCS1Padding");
toastLog(cipherText); // [114, 99, -93, 6, -88, 8, -12, -53, -68, -15, ...]

$crypto.decrypt(data, key, algorithm[, options])

• data {any} Ciphertext. The format depends on options.input.

• key {Key} Decryption key. Symmetric algorithms use a single key; asymmetric algorithms require a key pair. See Key.

• algorithm {string} Decryption algorithm, including:

  • AES
  • AES/ECB/NoPadding
  • AES/ECB/PKCS5Padding
  • AES/CBC/NoPadding
  • AES/CBC/PKCS5Padding
  • AES/CFB/NoPadding
  • AES/CFB/PKCS5Padding
  • AES/CTR/NoPadding
  • AES/CTR/PKCS5Padding
  • AES/OFB/PKCS5Padding
  • AES/OFB/PKCS5Padding
  • RSA/ECB/PKCS1Padding
  • RSA/ECB/NoPadding
  • ... (see javax.crypto.Cipher)

• options {Object} Optional. Specifies the input/output types and formats.

• Returns {any} Return type depends on options.

Decrypt data with key key using algorithm. data can be a file, binary, Base64, hex, string, etc. The decrypted result can be returned as binary/Base64/hex/string or written directly to a file, depending on options. See Input/output types and formats.

// AES encrypt, output as Base64
let key = new $crypto.Key("1234567890123456");
let cipherText = $crypto.encrypt("Hello, Auto.js Pro!", "AES", {
  input: "string",
  "output": "base64"
});
// AES decrypt, decode Base64 to string
let plaintext = $crypto.decrypt(cipherText, key, "AES", {
  "input": "base64",
  "output": "string"
});
toastLog(plaintext);

$crypto.generateKeyPair(algorithm[, length])

• algorithm {string} Algorithm, including:

  • DH
  • DSA
  • EC
  • RSA

• length {number} Key length. Depends on algorithm (e.g. modulus length in bits). Default 256.

• Returns {KeyPair}

Generate a key pair containing a public key and a private key. For RSA, you can encrypt with the private key and decrypt with the public key for signatures, or encrypt with the public key and decrypt with the private key for data encryption.

let keyPair = $crypto.generateKeyPair("RSA");
console.log("Public key:", keyPair.publicKey);
console.log("Private key:", keyPair.privateKey);

// Encrypt with public key, decrypt with private key
let plainText = "Hello World";
let bytes = $crypto.encrypt(plainText, keyPair.publicKey, "RSA");
let decryptedText = $crypto.decrypt(bytes, keyPair.privateKey, "RSA", {
    output: "string"
});
console.log(decryptedText);

// Decrypt with public key, encrypt with private key
let base64 = $crypto.encrypt(plainText, keyPair.privateKey, "RSA", {
    output: "base64"
});
decryptedText = $crypto.decrypt(base64, keyPair.publicKey, "RSA", {
    input: "base64",
    output: "string"
});
console.log(decryptedText);

Key

Key object. You can construct it directly, e.g. new Key('12345678').

new Key(data[, options])

• data {any} Key material. The format depends on options.input. Default is string.
• options {Object} Optional. See Input/output types and formats.

Constructor. Creates a Key object.

let key = new $crypto.Key('1234567890123456');
// Get key bytes
let data = key.data;
// Convert to Base64
let base64 = android.util.Base64.encodeToString(data, android.util.Base64.NO_WRAP);
// Reconstruct a Key from Base64
let copiedKey = new $crypto.Key(base64, \{input: "base64"\});
console.log(copiedKey.toString());

Key.data

• {byte[]}

Raw bytes of the key.

KeyPair

Key pair object. Can be generated by $crypto.generateKeyPair() or constructed via the constructor.

new KeyPair(publicKey, privateKey[, options])

[Added in Pro 8.7.2]

• publicKey {any} Public key data. Format depends on options.input. Default is string.
• privateKey {any} Private key data. Format depends on options.input. Default is string.
• options {Object} Optional. See Input/output types and formats.

Constructor. Creates a KeyPair object.

let keyPair = $crypto.generateKeyPair("RSA");
// Get public/private key bytes and convert to Base64
let data = {
  publicKey: base64Bytes(keyPair.publicKey.data),
  privateKey: base64Bytes(keyPair.privateKey.data),
};

// Reconstruct a KeyPair from Base64
let copiedKeyPair = new $crypto.KeyPair(data.publicKey, data.privateKey, \{input: "base64"\});
console.log(copiedKeyPair);

function base64Bytes(bytes) {
  return android.util.Base64.encodeToString(bytes, android.util.Base64.NO_WRAP);
}

KeyPair.privateKey

• {Key}

Private key.

KeyPair.publicKey

• {Key}

Public key.

Input/output types and formats

options {object} Specifies input/output types and formats for encryption, decryption, and digests.

• input {string} Input type. Specifies the source data type for encrypt/decrypt/digest. If the input is a string, default is string; otherwise default is bytes. Values:
  • string String data
  • base64 Base64 data
  • hex Hex (base16) data
  • bytes Java byte array
  • file File path. Reads data from a file for processing
• output {string} Output type. Specifies the result data type. For encrypt/decrypt, default is bytes; for digest, default is hex. Values:
  • string String data
  • base64 Base64 data
  • hex Hex (base16) data
  • bytes Java byte array
  • file File output. Writes result to a file; must also specify dest
• dest {string} Output file path used when output is file
• encoding {string} Character encoding. When input is string, used to encode the input string into bytes; when output is string, used to decode bytes into a string. Default utf-8
• iv {string} | {bytes} Initialization vector for AES etc (optional). Added in Pro 9.2.12.

let filepath = files.join("./test.txt", "1.txt");
let message = "Hello Autojs";
$files.write(filepath, message);

let str16 = "a".repeat(16);
let key = new $crypto.Key(str16);

// Base64 content to encrypt
let base64Content = $base64.encode(key);
// Hex content to encrypt
let hexContent = "48656c6c6f204175746f6a73";

// Encrypt a file, output as Base64
console.log($crypto.encrypt(filepath, key, "AES", \{ input: "file", output: "base64" \}));
// Encrypt a file, output to another file
console.log($crypto.encrypt(filepath, key, "AES", \{ input: "file", output: "file", dest: "./output.txt" \}));
// Encrypt Base64 content, output as Base64
console.log($crypto.encrypt("SGVsbG8gQXV0b2pz", key, "AES", \{ input: "base64", output: "base64" \}));
// Encrypt hex content, output as hex
console.log($crypto.encrypt("48656c6c6f204175746f6a73", key, "AES", \{ input: "hex", output: "hex" \}));
console.log($crypto.encrypt("Hello Autojs", key, "AES"));
// [-18, 27, -69, 81, 2, -87, -116, 23, -114, -86, -111, 40, 58, -127, -29, -59]

// Digest file MD5, output as hex
console.log($crypto.digest(filepath, "MD5", \{ input: "file", output: "hex" \}));

The Debug module provides debugging utilities such as diagnosing memory leaks and getting a detailed stack trace from an Error.

$debug.dumpHprof(file)

• file {string} Dump file path

Dump the memory of the entire script process to the given file.

If you find Auto.js Pro is using a lot of memory, you can run this function to dump memory and send it to the developer, who can use the dump file to diagnose potential memory leaks.

During dumping, the entire process may freeze. Do not operate the phone to avoid dump failure or other issues. Dumping usually takes tens of seconds to a few minutes; please wait patiently.

$debug.dumpHprof('./dump.hprof');

$debug.dumpAndSendHprof([file])

• file {string} Dump file path (optional). Default: dump.hprof.zip under the current directory.

Dump the process memory to file and automatically compress it into a zip file. It uses the highest compression level, which takes longer but produces a smaller file.

For more details, see $debug.dumpHprof.

$debug.getStackTrace(error)

• error {Error} Exception/Error
• Returns {string}

Get and return a detailed stack trace for an exception.

try {
    undefined_var;
} catch(e) {
    console.error($debug.getStackTrace(e));
}

$debug.setMemoryLeakDetectionEnabled(enabled)

• enabled {boolean} Whether to enable memory leak detection

When enabled, objects that are not manually recycled (e.g. images) will be reported in logs.

Currently detected objects include:

• Images

For example, the following code will cause a memory leak. After running for a while, you should see leak logs.

$debug.setMemoryLeakDetectionEnabled(true);
requestScreenCapture();

for (let i = 0; i < 10; i++) {
    // This image should have been recycled manually
    let leak = captureScreen().clone();

    // Intentionally comment out recycle
    // leak.recycle();
}
// Trigger GC
$debug.gc();

Tip

In Auto.js Pro runtime, this feature is enabled by default; in packaged apps, it is disabled by default.

$debug.gc()

Suggest the JVM to perform garbage collection (not guaranteed).

Stability: 2 - Stable

The device module provides device-related information and controls, such as screen size, memory usage, IMEI, and adjusting brightness/volume.

Some functions (e.g. adjusting volume) require the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.width

• {number}

Device screen width in pixels, e.g. 1080.

device.height

• {number}

Device screen height in pixels, e.g. 1920.

device.buildId

• {string}

Either a change list number, or a label like "M4-rc20".

Revision number or a label like "M4-rc20".

device.broad

• {string}

The name of the underlying board, like "goldfish".

Underlying board model.

device.brand

• {string}

The consumer-visible brand with which the product/hardware will be associated, if any.

Consumer-visible brand associated with the product/hardware, such as "Xiaomi", "Huawei", etc.

device.device

• {string}

The name of the industrial design.

Industrial design name of the device.

device.model

• {string}

The end-user-visible name for the end product.

Device model.

device.product

• {string}

The name of the overall product.

Overall product name.

device.bootloader

• {string}

The system bootloader version number.

Device bootloader version.

device.hardware

• {string}

The name of the hardware (from the kernel command line or /proc).

Hardware name (from kernel command line or /proc).

device.fingerprint

• {string}

A string that uniquely identifies this build. Do not attempt to parse this value.

Unique identifier string for this build.

device.serial

• {string}

A hardware serial number, if available. Alphanumeric only, case-insensitive.

Hardware serial number.

device.sdkInt

• {number}

The user-visible SDK version of the framework; its possible values are defined in Build.VERSION_CODES.

Android API level. For example, Android 4.4 has sdkInt 19.

device.incremental

• {string}

The internal value used by the underlying source control to represent this build. E.g., a perforce change list number or a git hash.

device.release

• {string}

The user-visible version string. E.g., "1.0" or "3.4b5".

Android release version string, such as "5.0", "7.1.1".

device.baseOS

• {string}

The base OS build the product is based on.

device.securityPatch

• {string}

The user-visible security patch level.

Security patch level.

device.codename

• {string}

The current development codename, or the string "REL" if this is a release build.

Development codename, e.g. "REL" for release builds.

device.getIMEI()

• {string}

Returns the device IMEI.

device.getAndroidId()

• {string}

Returns the device Android ID.

Android ID is a 64-bit integer represented as a hex string. It is randomly generated on first use and does not change unless the device is factory-reset.

device.getMacAddress()

• {string}

Returns the device MAC address. This requires an active WLAN connection; otherwise it returns null.

Possible future change: a root-based fallback may be added so it can return the correct MAC even without WLAN. Do not use this function to determine WLAN connectivity.

device.getBrightness()

• {number}

Returns current (manual) brightness in the range 0~255.

device.getBrightnessMode()

• {number}

Returns current brightness mode: 0 for manual, 1 for automatic.

device.setBrightness(b)

• b {number} Brightness, 0~255

Set current manual brightness. If the device is in auto-brightness mode, this will not affect the screen brightness.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setBrightnessMode(mode)

• mode {number} Brightness mode: 0 manual, 1 automatic

Set current brightness mode.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.getMusicVolume()

• {number} Integer value

Returns current media volume.

device.getNotificationVolume()

• {number} Integer value

Returns current notification volume.

device.getAlarmVolume()

• {number} Integer value

Returns current alarm volume.

device.getMusicMaxVolume()

• {number} Integer value

Returns max media volume.

device.getNotificationMaxVolume()

• {number} Integer value

Returns max notification volume.

device.getAlarmMaxVolume()

• {number} Integer value

Returns max alarm volume.

device.setMusicVolume(volume)

• volume {number} Volume

Set current media volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setNotificationVolume(volume)

• volume {number} Volume

Set current notification volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setAlarmVolume(volume)

• volume {number} Volume

Set current alarm volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.getBattery()

• {number} Float in range 0.0~100.0

Returns current battery level percentage.

device.isCharging()

• {boolean}

Returns whether the device is charging.

device.getTotalMem()

• {number}

Returns total device memory in bytes. 1MB = 1024 * 1024 bytes.

device.getAvailMem()

• {number}

Returns currently available memory in bytes.

device.isScreenOn()

• Returns {boolean}

Returns whether the screen is on. If on, returns true; otherwise false.

Note that some “always-on display” modes (e.g. certain vivo devices) are not considered “screen on”: although pixels are lit, it only shows a clock and is not interactive; isScreenOn() may still return false.

device.getScreenOrientation()

• Returns {string}

Returns the current screen orientation string.

Common values include portrait and landscape.

log("Screen orientation: " + device.getScreenOrientation());

device.getScreenRotation()

• Returns {number}

Returns current screen rotation in degrees.

Common values include 0, 90, 180, 270.

log("Screen rotation: " + device.getScreenRotation());

device.wakeUp()

Wake up the device, including CPU and screen. Can be used to turn on the screen.

device.wakeUpIfNeeded()

Wake up the device if the screen is not on.

device.keepScreenOn([timeout])

• timeout {number} How long to keep the screen on (ms). If omitted, keep on indefinitely.

Keep the screen on.

This cannot prevent the user from turning off the screen normally (e.g. power button). It only keeps the screen on while the device is idle. If the screen is off when called, it will wake the screen.

On some devices, if timeout is omitted, keeping the screen on may only work within the Auto.js UI and fail elsewhere due to power-saving policies. It's recommended to pass a long timeout instead of “keep indefinitely”, e.g. device.keepScreenOn(3600 * 1000).

Use device.cancelKeepingAwake() to cancel keeping the screen on.

// Keep screen on indefinitely
device.keepScreenOn()

device.keepScreenDim([timeout])

• timeout {number} How long to keep the screen awake (ms). If omitted, keep indefinitely.

Keep the screen awake but allow it to dim to save power. Useful for scheduled scripts that need the device awake but do not require the user to watch the screen.

This cannot prevent the user from turning off the screen normally. It only keeps the screen awake while idle. If the screen is off when called, it will wake the screen.

Use device.cancelKeepingAwake() to cancel keeping awake.

device.keepAwake([mode][, timeout])

• mode {number} Wake mode (optional)
• timeout {number} Wake duration in milliseconds (optional)

Keep the device awake. This is a lower-level API; usually prefer device.keepScreenOn() or device.keepScreenDim().

// Keep awake for 1 hour
device.keepAwake(0, 3600 * 1000);

device.cancelKeepingAwake()

Cancel keeping the device awake. Used to cancel device.keepScreenOn(), device.keepScreenDim(), etc.

device.vibrate(ms)

• ms {number} Vibration duration in milliseconds

Make the device vibrate for a period of time.

// Vibrate for 2 seconds
device.vibrate(2000);

device.cancelVibration()

Cancel vibration if the device is currently vibrating.

Shortcut Properties (Mirrors of Methods)

In addition to methods, device also provides shortcut properties that can be read directly.
These properties usually mirror the semantics of the corresponding getXxx() / isXxx() methods, making it convenient to read status quickly in scripts.

device.battery

• {number}

Current battery percentage (0~100), equivalent to device.getBattery().

device.brightness

• {number}

Current brightness (0~255), equivalent to device.getBrightness().

device.brightnessMode

• {number}

Current brightness mode: 0 manual, 1 automatic. Equivalent to device.getBrightnessMode().

device.charging

• {boolean}

Whether the device is charging, equivalent to device.isCharging().

device.screenOn

• {boolean}

Whether the screen is on, equivalent to device.isScreenOn().

device.screenOrientation

• {string}

Screen orientation. Common values: portrait or landscape. Equivalent to device.getScreenOrientation().

device.screenRotation

• {number}

Screen rotation in degrees. Common values: 0, 90, 180, 270. Equivalent to device.getScreenRotation().

device.totalMem

• {number}

Total device memory (bytes), equivalent to device.getTotalMem().

device.availMem

• {number}

Currently available memory (bytes), equivalent to device.getAvailMem().

device.androidId

• {string}

Device Android ID, equivalent to device.getAndroidId().

device.alarmVolume / device.alarmMaxVolume

• {number}

Current alarm volume and max alarm volume, equivalent to device.getAlarmVolume() and device.getAlarmMaxVolume().

device.musicVolume / device.musicMaxVolume

• {number}

Current media volume and max media volume, equivalent to device.getMusicVolume() and device.getMusicMaxVolume().

device.notificationVolume / device.notificationMaxVolume

• {number}

Current notification volume and max notification volume, equivalent to device.getNotificationVolume() and device.getNotificationMaxVolume().

Stability: 2 - Stable

The dialogs module provides simple dialog helpers for interacting with users. The simplest example:

alert("Hello");

This code shows an alert dialog with "Hello", and continues after the user taps "OK". A slightly more complex example:

var clear = confirm("Clear all cache?");
if (clear) {
  alert("Cleared!");
}

confirm() shows a dialog and lets the user choose "OK" or "Cancel". It returns true if the user confirms.

Important: in UI mode, dialogs cannot be used in the same blocking way as usual. Use callbacks or Promise instead. Example:

"ui";
// Callback style
confirm("Clear all cache?", function (clear) {
  if (clear) {
    alert("Cleared!");
  }
});
// Promise style
confirm("Clear all cache?").then((clear) => {
  if (clear) {
    alert("Cleared!");
  }
});

dialogs.alert(title[, content, callback])

• title {string} Dialog title.
• content {string} Optional. Dialog content. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows an alert dialog with only an OK button. The script continues after the user taps OK.

This function can also be used as a global function.

alert("Error", "Unknown error. Please contact the script author.");

In UI mode, this function returns a Promise. Example:

"ui";
alert("Hi").then(() => {
  // Runs after tapping OK
});

dialogs.confirm(title[, content, callback])

• title {string} Dialog title.
• content {string} Optional. Dialog content. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows a confirm dialog with OK and Cancel. Returns true if the user confirms, otherwise false.

This function can also be used as a global function.

In UI mode, this function returns a Promise. Example:

"ui";
confirm("Are you sure?").then((value) => {
  // value is true/false depending on OK/Cancel
});

dialogs.rawInput(title[, prefill, callback])

• title {string} Dialog title.
• prefill {string} Optional initial input value. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows an input dialog. Waits for user input and returns the entered string when the user taps OK. Returns null if the user cancels.

This function can also be used as a global function.

var name = rawInput("Your name", "Tom");
alert("Your name is " + name);

In UI mode, this function returns a Promise. Example:

"ui";
rawInput("Your name", "Tom").then((name) => {
  alert("Your name is " + name);
});

You can also use a callback, for example:

rawInput("Your name", "Tom", (name) => {
  alert("Your name is " + name);
});

dialogs.input(title[, prefill, callback])

Equivalent to eval(dialogs.rawInput(title, prefill, callback)). The difference from rawInput() is that it evaluates the returned string with eval() before returning it, so the return value may not be a string.

You can use it to input numbers, arrays, etc. Example:

var age = dialogs.input("Your age", "18");
// new Date().getYear() + 1900 returns the current year
var year = new Date().getYear() + 1900 - age;
alert("Your birth year is " + year);

In UI mode, this function returns a Promise. Example:

"ui";
dialogs.input("Your age", "18").then((age) => {
  var year = new Date().getYear() + 1900 - age;
  alert("Your birth year is " + year);
});

dialogs.prompt(title[, prefill, callback])

Equivalent to dialogs.rawInput().

dialogs.select(title, items, callback)

• title {string} Dialog title.
• items {Array} Options list (string array).
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a selection dialog and returns the selected option index (0 ~ item.length - 1). Returns -1 if the user cancels.

var options = ["Option A", "Option B", "Option C", "Option D"];
var i = dialogs.select("Select an option", options);
if (i >= 0) {
  toast("You selected: " + options[i]);
} else {
  toast("Cancelled");
}

In UI mode, this function returns a Promise. Example:

"ui";
dialogs
  .select("Select an option", ["Option A", "Option B", "Option C", "Option D"])
  .then((i) => {
    toast(i);
  });

dialogs.singleChoice(title, items[, index, callback])

• title {string} Dialog title.
• items {Array} Options list (string array).
• index {number} Default selected index. Default 0.
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a single-choice dialog and returns the selected option index (0 ~ item.length - 1). Returns -1 if the user cancels.

In UI mode, this function returns a Promise.

dialogs.multiChoice(title, items[, indices, callback])

• title {string} Dialog title.
• items {Array} Options list (string array).
• indices {Array} Default selected indices. Default empty array.
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a multi-choice dialog and returns an array of selected indices. Returns [] if the user cancels.

In UI mode, this function returns a Promise.

dialogs.setDefaultDialogType(type)

[Added in Pro 8.8.5]

• type {string} Dialog type

Sets the default dialog type. Supported values:

• overlay {string} Always show dialogs using the floating-window permission, regardless of foreground/background. Throws if floating-window permission is missing.
• app {string} Always show dialogs as in-app dialogs, regardless of whether the app is in the foreground. Throws if there is no UI. If the UI exists but is in the background, it will still be shown but the user will only see it after returning to the app. Note: Auto.js Pro main UI (file list) and the script process are not the same process, so you cannot show in-app dialogs on the Auto.js Pro main UI.
• app-or-overlay {string} If the app has a UI, show as an in-app dialog (may still show while backgrounded, but visible only after returning). If there is no UI, fall back to floating-window dialogs.
• foreground-or-overlay {string} If the app is in the foreground, use an in-app dialog; otherwise use a floating-window dialog, ensuring the user can see it immediately in all cases.

This affects all dialogs shown by the dialogs module. Custom dialogs created by $dialogs.build can override it via the type property.

If you don't call this function, the default is overlay (for backward compatibility).

// Make all dialogs default to foreground-or-overlay (alert, $dialogs.build(), etc.)
$dialogs.setDefaultDialogType("foreground-or-overlay");

let types = ["overlay", "app", "app-or-overlay", "foreground-or-overlay"];
let i = $dialogs.select("Select dialog type", [
  "Floating dialog: overlay",
  "In-app dialog: app",
  "Adaptive dialog: app-or-overlay",
  "Adaptive foreground dialog: foreground-or-overlay",
]);

if (i < 0) {
  exit();
}

let type = types[i];
alert(
  "Selected type: " + type + ". Tap OK and a dialog will be shown after 3 seconds.",
  "Within these 3 seconds, you can press back or switch to background to test dialog behavior.",
);

dialogs.build(properties)

• properties {Object} Dialog properties.
• Returns {Dialog}

Creates a customizable dialog. Example:

dialogs
  .build({
    // Dialog title
    title: "New version available",
    // Dialog content
    content: "Changelog: fixed several bugs",
    // Positive button
    positive: "Download",
    // Negative button
    negative: "Cancel",
    // Neutral button
    neutral: "Download in browser",
    // Checkbox prompt
    checkBoxPrompt: "Don't ask again",
  })
  .on("positive", () => {
    // On positive
    toast("Downloading...");
  })
  .on("neutral", () => {
    // On neutral
    app.openUrl("https://www.autojs.org");
  })
  .on("check", (checked) => {
    // On checkbox
    log(checked);
  })
  .show();

Available properties:

• title {string} Dialog title

• titleColor {string} | {number} Title color

• buttonRippleColor {string} | {number} Button ripple color

• icon {string} | {Image} Dialog icon (URL or Image object)

• content {string} Dialog content text

• contentColor{string} | {number} Content text color

• contentLineSpacing{number} Line-height multiplier for content text (1.0 = normal)

• customView {android.view.View} Custom view. You can create it from XML via ui.inflate.

• items {Array} List items

• itemsColor {string} | {number} List item text color

• itemsSelectMode {string} Selection mode:

  • select Normal selection
  • single Single-choice
  • multi Multi-choice

• itemsSelectedIndex {number} | {Array} Default selected index/indices (number for single, array for multi)

• positive {string} Positive button text (rightmost button)

• positiveColor {string} | {number} Positive button text color

• neutral {string} Neutral button text (leftmost button)

• neutralColor {string} | {number} Neutral button text color

• negative {string} Negative button text (left of positive)

• negativeColor {string} | {number} Negative button text color

• checkBoxPrompt {string} Checkbox prompt text

• checkBoxChecked {boolean} Default checkbox state

• progress {Object} Progress configuration:

  • max {number} Max value. -1 means indeterminate progress.
  • horizontal {boolean} If true, indeterminate progress is horizontal.
  • showMinMax {boolean} Whether to show min/max values

• cancelable {boolean} Whether the dialog is cancelable. If false, it can only be dismissed in code.

• canceledOnTouchOutside {boolean} Whether to cancel when tapping outside. Default true.

• inputHint {string} Input hint text

• inputPrefill {string} Default input value

• type {string} Dialog type. See $dialogs.setDefaultDialogType().

With these options you can customize a dialog, and implement interactions by listening to button/input events on the returned Dialog object. Here are some examples.

Alert-like dialog:

dialogs
  .build({
    title: "Hi",
    content: "Have a great day!",
    positive: "OK",
  })
  .show();

Confirm-like dialog:

dialogs
  .build({
    title: "Question",
    content: "Are you sure?",
    positive: "Yes",
    negative: "No",
  })
  .on("positive", () => {
    alert("Confirmed");
  })
  .on("negative", () => {
    alert("Cancelled");
  })
  .show();

Single-choice dialog:

dialogs
  .build({
    title: "Single choice",
    items: ["Option 1", "Option 2", "Option 3", "Option 4"],
    itemsSelectMode: "single",
    itemsSelectedIndex: 3,
  })
  .on("single_choice", (index, item) => {
    toast("You selected: " + item);
  })
  .show();