Macro Handler

Macro Handler

Android Automation Platform

API Reference

Macro Handler API Guide

All API objects, methods, and global functions available in Macro Handler scripts. Browse categories from the left panel or use the search.

Lua: Prefer ":" for instance method calls (example: region:find(Asset.image("target"), FindParam.timeout(3000)), match:click()).

Language and OCR scope

14 languages are selectable on both the website and the Android app settings. The website and Android app start in English on first open, and users can switch to their preferred language at any time.

70 official OCR language codes map to 7 OCR recognizer families: Latin, Chinese, Japanese, Korean, Devanagari, Arabic, and Cyrillic. Latin, Chinese, Japanese, Korean, and Devanagari use ML Kit recognizer packages; Arabic and Cyrillic use bundled Tesseract data for offline fallback. For scripts outside the official OCR coverage or rapidly changing glyph shapes, prefer template or image flows.

Trigger and Event scope

Macros can start manually from the dashboard, shortcuts, quick settings tile, and widget surfaces; the automatic trigger modes cover daily time (classic clock or an advanced cron expression), repeating interval, app launch and close, allowlisted notification posted and cleared, battery level, system broadcast, remote trigger (FCM/webhook), charger connected and disconnected, screen on and off, and volume key. Every trigger can be narrowed with an AND/OR/NOT constraint tree plus screen, charging, Wi-Fi, headset, device-unlock, orientation, battery, and time-of-day window conditions. On the script side, the Event object exposes source, kind, mode, macroId, packageName, appName, title, body, and at fields.

Total APIs

786

Global Functions

27

Global Objects

52

Object Methods

759

Global Functions

UI and Dialogs

Creates an on/off checkbox for dialogs.

lua
Try in Editor →
Checkbox(true, "Show notifications")
Touch and Actions

Performs tap action on a target coordinate.

lua
Try in Editor →
click(Point(540, 960))
-- or on a scan result: click(_lastMatch, ClickParam.repeat(2))
Other

ColorPicker - Macro Handler scripting API function.

lua
Try in Editor →
ColorPicker(value?)
Other

DateTimePicker - Macro Handler scripting API function.

lua
Try in Editor →
DateTimePicker(value?)
UI and Dialogs

Creates a text input field for dialogs.

lua
Try in Editor →
EditText("500", 1, "Delay (ms)")
Other

FilePicker - Macro Handler scripting API function.

lua
Try in Editor →
FilePicker(value?)
Touch and Actions

Defines start and end points for a swipe gesture.

lua
Try in Editor →
local sp = GesturePoint(Point(540, 1500), 0, 300)
UI and Dialogs

Creates an image picker component for dialogs.

lua
Try in Editor →
ImagePicker("target", "Select target image")
Touch and Actions

Creates a builder for constructing multi-swipe gestures.

lua
Try in Editor →
local msb = MultiGestureBuilder()
-- Add swipe points
Other

MultiSelect - Macro Handler scripting API function.

lua
Try in Editor →
MultiSelect(value?)
Core Flow

Shows in-app runtime messages on screen.

lua
Try in Editor →
notifyPro("Step completed")
Other

NumberRange - Macro Handler scripting API function.

lua
Try in Editor →
NumberRange(value?)
Core Flow

print - Macro Handler scripting API function.

lua
Try in Editor →
print("Log line")
Touch and Actions

Performs tap action on a target coordinate.

lua
Try in Editor →
local p = Point(540, 960)
quickTap(p)
UI and Dialogs

Creates a single-selection option group for dialogs.

lua
Try in Editor →
RadioGroup({"Slow", "Fast"}, 0)
Touch and Actions

Starts a touch gesture recorder.

lua
Try in Editor →
Recorder("record", "Record")
Core Flow

Requests a graceful stop for the current macro.

lua
Try in Editor →
if not License.isValid() then
  requestStop()
end
Other

SignaturePad - Macro Handler scripting API function.

lua
Try in Editor →
SignaturePad(value?)
Core Flow

sleep - Macro Handler scripting API function.

lua
Try in Editor →
sleep(0.5)
Other

Slider - Macro Handler scripting API function.

lua
Try in Editor →
Slider(value?)
Other

Spacer - Macro Handler scripting API function.

lua
Try in Editor →
Spacer(value?)
Touch and Actions

Executes swipe movement between two coordinates.

lua
Try in Editor →
swipe({GesturePoint(Point(540, 1500), 0, 0), GesturePoint(Point(540, 500), 0, 300)})
UI and Dialogs

Defines a tabbed panel layout for dialogs.

lua
Try in Editor →
TabLayout({"General", "Advanced"})
Other

TagInput - Macro Handler scripting API function.

lua
Try in Editor →
TagInput(value?)
UI and Dialogs

Creates a read-only text label for dialogs.

lua
Try in Editor →
TextView("Header Text")
Core Flow

Shows in-app runtime messages on screen.

lua
Try in Editor →
toast("Macro started")
Core Flow

Creates a millisecond delay in script execution flow.

lua
Try in Editor →
wait(500)
wait(1000)

Other

Methods: 2Singleton Global

AI is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- AI:ask
local result = AI:ask("value")
-- Use the result in your script flow

Data and Files

Methods: 8Singleton Global

Array is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Array:sort
local result = Array:sort("value")
-- Use the result in your script flow

Scanning and Detection

Methods: 11Singleton Global

Asset manages screen scanning, image matching, and detection flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
local tpl = Asset.image("play_btn")
local reg = Region()
reg:find(tpl)

Other

Methods: 20Singleton Global

AssetTemplate is part of the Macro Handler API surface.

Foundation Example

lua
Try in Editor →
-- AssetTemplate:value
local result = AssetTemplate:value("value")
-- Use the result in your script flow

Other

Methods: 8Singleton Global

Async is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Async:promise
local result = Async:promise("value")
-- Use the result in your script flow

Other

Methods: 7Singleton Global

AsyncPromise is part of the Macro Handler API surface.

Foundation Example

lua
Try in Editor →
-- AsyncPromise:resolve
local result = AsyncPromise:resolve("value")
-- Use the result in your script flow

Scanning and Detection

Methods: 5Singleton Global

Capture manages screen scanning, image matching, and detection flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Capture:stop
local result = Capture:stop()
-- Use the result in your script flow

Parameter Objects

Methods: 7Singleton Global

ClickParam configures detailed search/action parameters. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- ClickParam:repeat
local result = ClickParam:repeat("value")
-- Use the result in your script flow

Data and Files

Methods: 4Singleton Global

Clipboard is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Clipboard:clear
local result = Clipboard:clear()
-- Use the result in your script flow

Other

Methods: 10Singleton Global

Collection is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Collection:put
local result = Collection:put("my_collection", "value")
-- Use the result in your script flow

Scanning and Detection

Methods: 27Factory Global

Color manages screen scanning, image matching, and detection flow. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Color:pixel
local result = Color:pixel("value")
-- Use the result in your script flow

UI and Dialogs

Methods: 3Singleton Global

Console is used to build dialogs, settings, or HUD overlays. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Console:out
local result = Console:out("value")
-- Use the result in your script flow

Other

Methods: 18Singleton Global

Crypto is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Crypto:md5
local result = Crypto:md5("value")
-- Use the result in your script flow

Date and Time

Methods: 32Factory Global

DateTime is used for date, duration, and timing operations. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
local now = DateTime.now()
toast(DateTime.format(now, "yyyy-MM-dd HH:mm"))

Other

Methods: 1Factory Global

Dialog is part of the Macro Handler API surface. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Dialog:init
local result = Dialog:init("value")
-- Use the result in your script flow

Other

Methods: 3Singleton Global

Env is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Env:setMacroCutouts
local result = Env:setMacroCutouts("value")
-- Use the result in your script flow

Other

Methods: 11Singleton Global

Event is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Event:exists
local result = Event:exists()
-- Use the result in your script flow

Other

Methods: 6Singleton Global

Events is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Events:on
local result = Events:on("value")
-- Use the result in your script flow

Data and Files

Methods: 16Singleton Global

File is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
File.write("run.log", "Started")
local txt = File.read("run.log")

Parameter Objects

Methods: 16Singleton Global

FindParam configures detailed search/action parameters. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- FindParam:timeout
local result = FindParam:timeout("value")
-- Use the result in your script flow

UI and Dialogs

Methods: 37Factory Global

Hud is used to build dialogs, settings, or HUD overlays. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
local hud = Hud(10, 10, 200, 50, true)
hud:setText("Running")
hud:setTextColor("#FFFFFF")
hud:setBackgroundColor("#80000000")
hud:show()

Other

Methods: 2Singleton Global

Humanize is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Humanize:setLevel
local result = Humanize:setLevel("value")
-- Use the result in your script flow

Data and Files

Methods: 2Singleton Global

JSON is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- JSON:parse
local result = JSON:parse("sample text", "%d+")
-- Use the result in your script flow

Data and Files

Methods: 14Singleton Global

KV is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- KV:set
local result = KV:set("my_key", "value")
-- Use the result in your script flow

License and Security

Methods: 9Singleton Global

License is used in license and access validation flows. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
if License.isActive() then
  toast("License active")
end

Other

Methods: 4Singleton Global

Macro is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Macro:list
local result = Macro:list("value")
-- Use the result in your script flow

Data and Files

Methods: 17Factory Global

Map is part of the Macro Handler API surface. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Map:get
local result = Map:get("my_key")
-- Use the result in your script flow

Data and Files

Methods: 9Singleton Global

Math is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Math:randomRange
local result = Math:randomRange("value")
-- Use the result in your script flow

System Control

Methods: 4Singleton Global

Metrics provides system/device level helper methods. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Metrics:enable
local result = Metrics:enable("value")
-- Use the result in your script flow

Touch and Actions

Methods: 5Singleton Global

MultiGesture handles tap, swipe, and action execution flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- MultiGesture:builder
local result = MultiGesture:builder("value")
-- Use the result in your script flow

Data and Files

Methods: 14Singleton Global

Num is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Num:parse
local result = Num:parse("sample text", "%d+")
-- Use the result in your script flow

Touch and Actions

Methods: 17Singleton Global

Panel handles tap, swipe, and action execution flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Panel:show
local result = Panel:show()
-- Use the result in your script flow

Parameter Objects

Methods: 7Singleton Global

PlayParam configures detailed search/action parameters. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- PlayParam:repeat
local result = PlayParam:repeat("value")
-- Use the result in your script flow

Touch and Actions

Methods: 9Factory Global

Point handles tap, swipe, and action execution flow. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Point:x
local result = Point:x("value")
-- Use the result in your script flow

Data and Files

Methods: 5Singleton Global

Regex is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Regex:match
local result = Regex:match("value")
-- Use the result in your script flow

Scanning and Detection

Methods: 74Factory Global

Region manages screen scanning, image matching, and detection flow. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
local area = Region()
local hit = area:find(Asset.image("ok_btn"))
if hit then quickTap(hit) end

Touch and Actions

Methods: 7Singleton Global

Replay handles tap, swipe, and action execution flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Replay:start
local result = Replay:start({})
-- Use the result in your script flow

Network and Integration

Methods: 13Factory Global

Request is used for external service communication. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
local res = Request.get("https://example.com")
toast("HTTP: " .. tostring(res:getResponseCode()))

Scanning and Detection

Methods: 7Singleton Global

Result manages screen scanning, image matching, and detection flow.

Foundation Example

lua
Try in Editor →
-- Result:getPoint
local result = Result:getPoint()
-- Use the result in your script flow

System Control

Methods: 25Singleton Global

Runtime provides system/device level helper methods. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Runtime:get
local result = Runtime:get()
-- Use the result in your script flow

UI and Dialogs

Methods: 10Singleton Global

Setting is used to build dialogs, settings, or HUD overlays. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
local cfg = Setting.builder()
cfg:add("delay", EditText("500", 1, "Delay"))
Setting.setDialog(cfg:build())
Setting.show()

UI and Dialogs

Methods: 7Singleton Global

SettingBuilder is used to build dialogs, settings, or HUD overlays.

Foundation Example

lua
Try in Editor →
-- SettingBuilder:setTitle
local result = SettingBuilder:setTitle("value")
-- Use the result in your script flow

Scanning and Detection

Methods: 11Singleton Global

Snap manages screen scanning, image matching, and detection flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
Snap.screenRefresh()
local r = Region()
local found = r:find(Asset.image("start_btn"))

Other

Methods: 2Singleton Global

SSE is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- SSE:read
local result = SSE:read("macro.log")
-- Use the result in your script flow

Date and Time

Methods: 14Factory Global

Stopwatch is used for date, duration, and timing operations. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Stopwatch:start
local result = Stopwatch:start({})
-- Use the result in your script flow

Data and Files

Methods: 25Singleton Global

Str is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Str:contains
local result = Str:contains("sample text", "sample text")
-- Use the result in your script flow

Parameter Objects

Methods: 6Singleton Global

SwipeParam configures detailed search/action parameters. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- SwipeParam:repeat
local result = SwipeParam:repeat("value")
-- Use the result in your script flow

System Control

Methods: 72Singleton Global

System provides system/device level helper methods. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- System:currentTime
local result = System:currentTime("value")
-- Use the result in your script flow

Date and Time

Methods: 34Factory Global

TimeSpan is used for date, duration, and timing operations. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- TimeSpan:fromMs
local result = TimeSpan:fromMs("value")
-- Use the result in your script flow

Other

Methods: 17Factory Global

ToastParams is part of the Macro Handler API surface. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- ToastParams:setDuration
local result = ToastParams:setDuration("value")
-- Use the result in your script flow

Touch and Actions

Methods: 13Singleton Global

Touch handles tap, swipe, and action execution flow. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
Touch.down(Point(500, 1200), 0)
wait(80)
Touch.up(0)

Other

Methods: 19Singleton Global

Tune is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Tune:setMinScore
local result = Tune:setMinScore("value")
-- Use the result in your script flow

Other

Methods: 6Singleton Global

Ui is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Ui:findNode
local result = Ui:findNode(Asset.image("target"), FindParam.timeout(3000))
-- Use the result in your script flow

Other

Methods: 1Singleton Global

Utils is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- Utils:interpolatePoints
local result = Utils:interpolatePoints("value")
-- Use the result in your script flow

System Control

Methods: 16Factory Global

Version provides system/device level helper methods. It also behaves as a callable global factory.

Foundation Example

lua
Try in Editor →
-- Version:code
local result = Version:code("value")
-- Use the result in your script flow

Other

Methods: 10Singleton Global

WebSocket is part of the Macro Handler API surface. It is exposed as a singleton global namespace.

Foundation Example

lua
Try in Editor →
-- WebSocket:exchange
local result = WebSocket:exchange("value")
-- Use the result in your script flow

Detailed Usage Examples

Ready-to-use examples you can paste directly into the code editor and run. Each example includes detailed descriptions and parameters.

20 examples