#Integrate with Android (adb)

After connecting the Android device with adb, you can use Midscene javascript SDK to control Android devices.

#Preparation

#Install Node.js

Install Node.js 18 or above globally.

#Prepare an API Key

Prepare an API key from a visual-language (VL) model. You will use it later.

You can check the supported models in Choose a model

#Install adb

adb is a command-line tool that allows you to communicate with an Android device. There are two ways to install adb:

• way 1: use Android Studio to install
• way 2: use Android command-line tools to install

Verify adb is installed successfully:

adb --version

When you see the following output, adb is installed successfully:

Android Debug Bridge version 1.0.41
Version 34.0.4-10411341
Installed as /usr/local/bin//adb
Running on Darwin 24.3.0 (arm64)

#Set environment variable ANDROID_HOME

Reference Android environment variables, set the environment variable ANDROID_HOME.

Verify the ANDROID_HOME variable is set successfully:

echo $ANDROID_HOME

When the command has any output, the ANDROID_HOME variable is set successfully:

/Users/your_username/Library/Android/sdk

#Connect Android device with adb

In the developer options of the system settings, enable the 'USB debugging' of the Android device, if the 'USB debugging (secure settings)' exists, also enable it, then connect the Android device with a USB cable

Verify the connection:

adb devices -l

When you see the following output, the connection is successful:

List of devices attached
s4ey59	device usb:34603008X product:cezanne model:M2006J device:cezan transport_id:3

#Setup AI model service

Set your model configs into the environment variables. You may refer to choose a model for more details.

# replace with your own
export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

#Step 1. install dependencies

npm install @midscene/android --save-dev

#Step 2. write scripts

Let's take a simple example: search for headphones on eBay using the browser in the Android device. （Of course, you can also use any other apps on the Android device.）

Write the following code, and save it as ./demo.ts

import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
Promise.resolve(
  (async () => {
    const devices = await getConnectedDevices();
    const page = new AndroidDevice(devices[0].udid);

    // 👀 init Midscene agent
    const agent = new AndroidAgent(page,{
      aiActionContext:
        'If any location, permission, user agreement, etc. popup, click agree. If login page pops up, close it.',
    });
    await page.connect();

    // 👀 open browser and navigate to ebay.com (Please ensure that the current page has a browser app)
    await agent.aiAction('open browser and navigate to ebay.com');

    await sleep(5000);

    // 👀 type keywords, perform a search
    await agent.aiAction('type "Headphones" in search box, hit Enter');

    // 👀 wait for loading completed
    await agent.aiWaitFor("There is at least one headphone product");
    // or you can use a normal sleep:
    // await sleep(5000);

    // 👀 understand the page content, extract data
    const items = await agent.aiQuery(
      "{itemTitle: string, price: Number}[], find item in list and corresponding price"
    );
    console.log("headphones in stock", items);

    // 👀 assert by AI
    await agent.aiAssert("There is a category filter on the left");
  })()
);

#Step 3. run

Using tsx to run

# run
npx tsx demo.ts

After a while, you will see the following output:

[
{
  itemTitle: 'Beats by Dr. Dre Studio Buds Totally Wireless Noise Cancelling In Ear + OPEN BOX',
  price: 505.15
},
{
  itemTitle: 'Skullcandy Indy Truly Wireless Earbuds-Headphones Green Mint',
  price: 186.69
}
]

#Step 4: view the report

After the above command executes successfully, the console will output: Midscene - report file updated: /path/to/report/some_id.html. You can open this file in a browser to view the report.

#AndroidDevice constructor

The AndroidDevice constructor supports the following parameters:

• deviceId: string - The device id
• opts?: AndroidDeviceOpt - Optional, the options for the AndroidDevice
  • autoDismissKeyboard?: boolean - Optional, whether to dismiss the keyboard after inputting. (Default: true)
  • androidAdbPath?: string - Optional, the path to the adb executable.
  • remoteAdbHost?: string - Optional, the remote adb host.
  • remoteAdbPort?: number - Optional, the remote adb port.

#More interfaces in AndroidAgent

Except the common agent interfaces in API Reference, AndroidAgent also provides some other interfaces:

#agent.launch()

Launch a webpage or native page.

• Type

function launch(uri: string): Promise<void>;

• Parameters:

  • uri: string - The uri to open, can be a webpage url or a native app's package name or activity name, if the activity name exists, it should be separated by / (e.g. com.android.settings/.Settings).

• Return Value:

  • Returns a Promise that resolves to void when the page is opened.

• Examples:

import { AndroidAgent, AndroidDevice } from '@midscene/android';

const page = new AndroidDevice('s4ey59');
const agent = new AndroidAgent(page);

await agent.launch('https://www.ebay.com'); // open a webpage
await agent.launch('com.android.settings'); // open a native page
await agent.launch('com.android.settings/.Settings'); // open a native page

#agentFromAdbDevice()

Create a AndroidAgent from a connected adb device.

• Type

function agentFromAdbDevice(deviceId?: string, opts?: PageAgentOpt): Promise<AndroidAgent>;

• Parameters:

  • deviceId?: string - Optional, the adb device id to connect. If not provided, the first connected device will be used.
  • opts?: PageAgentOpt & AndroidDeviceOpt - Optional, the options for the AndroidAgent, PageAgentOpt refer to constructor, AndroidDeviceOpt refer to AndroidDevice constructor.

• Return Value:

  • Promise<AndroidAgent> Returns a Promise that resolves to an AndroidAgent.

• Examples:

import { agentFromAdbDevice } from '@midscene/android';

const agent = await agentFromAdbDevice('s4ey59'); // create a AndroidAgent from a specific adb device
const agent = await agentFromAdbDevice(); // no deviceId, use the first connected device

#getConnectedDevices()

Get all connected Android devices.

• Type

function getConnectedDevices(): Promise<Device[]>;
interface Device {
  /**
   * The device udid.
   */
  udid: string;
  /**
   * Current device state, as it is visible in
   * _adb devices -l_ output.
   */
  state: string;
  port?: number;
}

• Return Value:

  • Promise<Device[]> Returns a Promise that resolves to an array of Device.

• Examples:

import { agentFromAdbDevice, getConnectedDevices } from '@midscene/android';

const devices = await getConnectedDevices();
console.log(devices);
const agent = await agentFromAdbDevice(devices[0].udid);

#More

• For all the APIs on the Agent, please refer to API Reference.
• For more details about prompting, please refer to Prompting Tips

#FAQ

#Why can't I control the device even though I've connected it?

Please check if the device is unlocked in the developer options of the system settings.

#How to use a custom adb path, remote adb host and port?

You can use the MIDSCENE_ADB_PATH environment variable to specify the path to the adb executable, MIDSCENE_ADB_REMOTE_HOST environment variable to specify the remote adb host, MIDSCENE_ADB_REMOTE_PORT environment variable to specify the remote adb port.

export MIDSCENE_ADB_PATH=/path/to/adb
export MIDSCENE_ADB_REMOTE_HOST=192.168.1.100
export MIDSCENE_ADB_REMOTE_PORT=5037

Additionally, you can also specify the adb path, remote adb host and port through the AndroidDevice constructor.

const device = new AndroidDevice('s4ey59', {
  androidAdbPath: '/path/to/adb',
  remoteAdbHost: '192.168.1.100',
  remoteAdbPort: 5037,
});