Android Toolkit

@skrillex1224/android-toolkit is the native Android counterpart to @skrillex1224/playwright-toolkit.

Actor code should import only useAndroidToolKit() and then use the returned modules. The public API is intentionally small and destructive from v1 onward.

import { useAndroidToolKit } from '@skrillex1224/android-toolkit';

const { Launch } = useAndroidToolKit();

await Launch.run(async ({ ctx, kit }) => {
  const { ApifyKit, DeviceInput, Mutation, Share } = kit;
  await ApifyKit.runStep('输入并发送', ctx, async () => {
    await DeviceInput.click(ctx, { id: 'input_text' });
    await DeviceInput.fill(ctx, { id: 'input_text' }, ctx.query);
    await DeviceInput.click(ctx, { id: 'action_send' });
  });
  await Mutation.waitForStable(ctx, { id: 'message_list' });
  const screenshotBase64 = await Share.captureScreen(ctx);
  await ApifyKit.pushArtifact({ screenshotBase64 });
});

Public Modules

| Module | Responsibility | | --- | --- | | Launch | Native actor entrypoint with fixed /apify_storage/input.json and /apify_storage/output.json paths plus lifecycle hooks. | | ApifyKit | runStep, runStepLoose, pushSuccess, pushFailed, pushArtifact. | | Device | Low-level ADB primitives only. | | DeviceView | Native View-tree snapshot and selector lookup over uiautomator dump. | | DeviceInput | View-tree-backed click/fill/press/scroll APIs using ADB input. | | Mutation | Playwright-like stable wait semantics over matched ViewNode subtrees. | | Share | Sprite screenshot and clipboard share-link polling. | | DeviceSQLite | Root ADB-backed private SQLite snapshot queries. | | Constants | Native-useful actor metadata and codes. | | Errors | CrawlerError and error serialization. |

Runtime Contract

The toolkit does not install or discover runtime tools.

Required environment:

• ANDROID_TOOLKIT_ADB_PATH

Device initialization, Appium Settings, UnicodeIME, and root ADB access belong to manager/cluster runtime. Runtime checks fail clearly when prerequisites are missing.

Boundaries

Included:

• ADB command execution, app launch, key input, screenshot, activity checks.
• View-tree parsing with a real XML parser.
• View selector operations: id, text, textContains, contentDesc, className.
• Root ADB-backed SQLite queries through DeviceSQLite.query() only.

Excluded:

• Public generic process injection or app hook execution.
• App hook clipboard helpers.
• WebView event recorder.
• App hook UI traversal/click helpers.
• Package name and activity truth. Backend/runtime input owns those values.
• Actor-specific DB schemas, message parsing, product parsing, and success criteria.

Android Actor Rules

• Do not use hardcoded absolute coordinates, screen-ratio coordinates, or naked point taps in actor code.
• Do not add fallback clicks. If the expected selector, DOM element, activity, or key-driven flow is unavailable, fail with a typed error and useful context.
• UI actions must be driven by one of: native DeviceView selectors, WebView DOM actions, Android activity/intents, or deterministic key events with activity/state verification.
• If an app renders custom UI that is invisible to uiautomator, use a stable app/runtime capability instead of guessing screen positions.
• Bounds-based taps are allowed only when the bounds come from a located native view; WebView clicks must stay in WebView.click/WebView.evaluate.

Browser Entry

@skrillex1224/android-toolkit/browser exports only Constants and Errors.