# Tự động hóa giả lập Android bằng Python: bắt đầu

> Tự động hóa giả lập Android bằng Python trong Macro Automation Studio: kết nối thiết bị, chạy bot từ Marketplace, nhờ MAS Agent hoặc tự viết macro đầu tiên.

Source: https://automationmacro.com/vi/docs/getting-started (Bắt đầu, updated 2026-09-05)

Tự động hóa giả lập Android bằng Python trong Macro Automation Studio (MAS) làm việc qua màn hình: MAS nhìn vào thiết bị, tìm thứ nó cần và chạm. Trang này đưa bạn từ bản cài mới đến macro Python đầu tiên chạy trên giả lập Android, thiết bị cloud hoặc điện thoại của bạn. Trang dành cho người dùng lần đầu trên Windows hoặc Mac.

## Trước khi bắt đầu

- MAS đã cài và bạn đã đăng nhập. Xem [Cài đặt MAS](/docs/install).
- Bạn có thứ để tự động hóa: một giả lập Android trên máy tính này, một thiết bị cloud, hoặc điện thoại của chính bạn. Xem [Thiết bị](/docs/devices).
- Tài khoản của bạn có gói đăng ký đang hoạt động hoặc bản dùng thử miễn phí. Mọi trang trong ứng dụng, trừ đăng nhập và **Gói đăng ký**, đều cần điều này. Không có nó, MAS mở trang **Gói đăng ký** và dừng ở đó. Các gói nằm ở [trang giá](/pricing).

> [!NOTE]
> Python SDK đã được cài sẵn. MAS mang theo môi trường Python 3.13 riêng với gói `mas`, nên `import mas` chạy được ngay trong Code Editor mà bạn không phải cài gì thêm.

## Cài đặt Macro Automation Studio: chọn thiết bị

Mỗi lần chạy nhắm vào một thiết bị. Chọn loại phù hợp:

| Thiết bị | Chạy ở đâu | Phù hợp với |
|---|---|---|
| Giả lập (BlueStacks, LDPlayer, MuMu Player, MEmu) | Trên máy tính này, qua adb | Bước đầu và thử nghiệm tại chỗ |
| Thiết bị cloud | Trong cloud của MAS, truyền hình về ứng dụng qua WebRTC | Lần chạy tiếp tục khi máy tính của bạn tắt |
| Điện thoại của bạn | Trên máy tính này, qua adb (nâng cao) | Ứng dụng chỉ hoạt động đúng trên phần cứng thật |

Để thêm giả lập:

1. Khởi động giả lập và bật ADB trong phần cài đặt của nó. Mỗi hướng dẫn giả lập chỉ rõ chỗ đặt tùy chọn này.
2. Trong MAS, mở **Nhóm thiết bị** và nhấn **Tạo nhóm mới**. Giữ loại **Local**.
3. Mở nhóm và nhấn **Thêm thiết bị**.
4. Nhập **Tên thiết bị** và chọn cổng của giả lập trong danh sách **Cổng**. Nhấn **Làm mới** nếu danh sách trống.
5. Nhấn **Thêm thiết bị**.

Thiết bị cloud được tạo trên trang **Thiết bị cloud** bằng nút **Tạo** và xuất hiện làm đích chạy bên cạnh thiết bị local. Cách dùng điện thoại được mô tả ở trang [Thiết bị](/docs/devices).

## Ba cách để có macro

### Chạy bot từ Marketplace

1. Mở **Marketplace** và tìm ứng dụng hoặc game.
2. Mở một mục và nhấn **Tải xuống**. Bot xuất hiện trong **Macro**, gắn nhãn "Tải từ Marketplace".
3. Trong **Nhóm thiết bị**, mở nhóm của bạn, chọn bot trong ô **Macro** của thiết bị và nhấn **Bắt đầu**.
4. Theo dõi tab **Nhật ký** trên thẻ thiết bị. Nhấn **Dừng** khi xong.

Hướng dẫn đầy đủ kèm ảnh chụp là [Cách chạy macro từ Marketplace](/docs/run-macro-from-marketplace). Cách đăng bot của riêng bạn nằm ở trang [Marketplace](/docs/marketplace).

### Nhờ MAS Agent

1. Mở **Agent** và chọn thiết bị trong **Thiết bị**.
2. Mô tả tác vụ bằng lời thường và nhấn **Viết macro**.
3. Trả lời khi thẻ "Agent cần bạn trả lời" xuất hiện. Agent dừng lại hỏi thay vì đoán.
4. Khi macro vượt qua 3 lần chạy kiểm chứng, nhấn **Thêm vào Macro của tôi**.

Kết quả là một dự án Python bình thường, mở được trong Code Editor. Việc viết tiêu tốn credit AI; chạy macro đã hoàn thành thì không tốn gì. Đọc thêm ở trang [MAS Agent](/docs/agent).

### Tự động hóa giả lập Android bằng Python

1. Mở **Macro** và nhấn **Tạo dự án mới**.
2. Chọn **Code-Based**, đặt **Thiết bị đích** là mobile, đặt tên dự án và nhấn **Tạo dự án**.
3. Mở dự án. Code Editor hiển thị `src/app.py`. Dán đoạn mã bên dưới vào.
4. Chọn thiết bị và nhấn **Chạy** (<kbd>F5</kbd>). **Dừng** là <kbd>Shift</kbd>+<kbd>F5</kbd> và **Lưu** là <kbd>Ctrl</kbd>+<kbd>S</kbd>.

[Tổng quan SDK](/docs/sdk) giải thích các namespace; [tài liệu API](/docs/api-reference) liệt kê mọi hàm.

## Đoạn mã đầu tiên của bạn

Đoạn mã này đọc thông tin thiết bị, chụp màn hình và chạy OCR trên toàn màn hình. Không có gì trên thiết bị thay đổi.

```python
import mas

device = mas.get_device_info()
print(f"Connected to: {device.name}")

screen = mas.get_screen_size()
print(f"Screen: {screen.width}x{screen.height}")

shot = mas.take_screenshot()
print(f"Screenshot: {shot.width}x{shot.height}")

result = mas.read_text()
print(f"Screen text: {result.text[:100]}")

mas.log("First script finished")
```

`mas.log` ghi một dòng có cấp độ vào bảng điều khiển chạy. `print` thường cũng dùng được.

## Các mẫu thường gặp

### Tìm một ảnh và chạm vào nó

Cắt nút trong Asset Lab để nó vào Thư viện ảnh của bạn với một ID, rồi khai báo bằng `mas.images`. `find_object_retry` tìm tối đa ba lần, cách nhau hai giây, và trả về `None` khi không khớp gì.

```python
import mas

images = mas.images({"play_button": 42})

match = mas.find_object_retry(images.play_button, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y, delay_ms=1000)
else:
    mas.log("Play button not found", level="warning")
```

`find_object` khớp với ngưỡng 0.8 theo mặc định. `click` chờ 1000 ms sau khi chạm để ứng dụng kịp phản ứng; giảm `delay_ms` trong các vòng lặp nhanh.

### Đọc chữ trong một vùng

```python
import mas
from mas import Region

score = mas.read_text(region=Region(x1=800, y1=10, x2=1050, y2=60), psm=7)
if score.text.strip().isdigit():
    print(f"Current score: {int(score.text)}")
```

`psm=7` coi vùng là một dòng đơn, hợp với các bộ đếm. Vẽ vùng trong Asset Lab và thử trực tiếp trước khi chép tọa độ.

### Xử lý lỗi

```python
import mas

try:
    match = mas.find_object_retry(42)
    if match:
        mas.click(match.x, match.y)
except mas.DeviceNotConnectedError:
    mas.log("No device connected", level="error")
except mas.ImageNotFoundError:
    mas.log("Image ID is not in your library", level="error")
except mas.TimeoutError:
    mas.log("The device did not answer in time", level="error")
except mas.RPCError as e:
    mas.log(f"RPC error: {e}", level="error")
```

## Khắc phục sự cố

### Could not discover RPC port

Đoạn mã được khởi chạy ngoài MAS, hoặc ứng dụng chưa chạy. Chạy mã từ Code Editor hoặc từ thẻ thiết bị; ứng dụng khởi chạy chúng kèm thông tin kết nối.

### Ứng dụng mở Gói đăng ký thay vì trang tôi nhấn

Quyền truy cập của bạn bị thiếu hoặc đã hết hạn. Bắt đầu dùng thử hoặc chọn gói, rồi quay lại. Xem [Thanh toán](/docs/billing).

### Không tìm thấy thiết bị hoặc kẹt ở Đang kết nối

ADB của giả lập đang tắt, giả lập vẫn đang khởi động, hoặc nó nghe trên cổng khác. Xem [Khắc phục sự cố ADB](/docs/adb-troubleshooting).