파이썬 안드로이드 자동화 시작하기: 첫 매크로 실행

파이썬 안드로이드 자동화 도구인 Macro Automation Studio(MAS)는 화면을 통해 Android 앱을 조작합니다. 기기 화면을 보고, 필요한 것을 찾고, 탭합니다. 이 페이지는 파이썬 안드로이드 자동화를 처음 시작하는 분을 위해, 설치 직후부터 Android 에뮬레이터, 클라우드 기기 또는 휴대폰에서 첫 파이썬 매크로를 실행하기까지의 과정을 다룹니다. Windows와 Mac 모두 해당됩니다.

시작하기 전에

• MAS가 설치되어 있고 로그인한 상태여야 합니다. MAS 설치를 참고하세요.
• 자동화할 대상이 있어야 합니다: 이 컴퓨터의 Android 에뮬레이터, 클라우드 기기, 또는 본인의 휴대폰. 기기를 참고하세요.
• 계정에 활성 구독 또는 무료 체험이 있어야 합니다. 로그인과 Subscription을 제외한 앱의 모든 페이지에 필요합니다. 없으면 MAS는 Subscription을 열고 거기서 멈춥니다. 요금제는 가격 페이지에 있습니다.

안드로이드 에뮬레이터 매크로 설정: 기기 선택

실행은 기기 하나를 대상으로 합니다. 상황에 맞는 종류를 고르세요:

에뮬레이터를 추가하려면:

1. 에뮬레이터를 시작하고 설정에서 ADB를 켭니다. 어디에 설정이 있는지는 각 에뮬레이터 가이드에 나와 있습니다.
2. MAS에서 Device Groups를 열고 Create New Group을 클릭합니다. 유형은 Local로 둡니다.
3. 그룹을 열고 Add Device를 클릭합니다.
4. Device Name을 입력하고 Port 목록에서 에뮬레이터의 포트를 고릅니다. 목록이 비어 있으면 Refresh를 클릭합니다.
5. Add Device를 클릭합니다.

클라우드 기기는 Cloud Devices 페이지에서 Create로 만들며, 로컬 기기 옆에 실행 대상으로 나타납니다. 휴대폰 연결 방법은 기기 페이지에 있습니다.

매크로를 얻는 세 가지 방법

마켓플레이스 봇 실행

1. Marketplace를 열고 앱이나 게임을 검색합니다.
2. 목록을 열고 Download를 클릭합니다. 봇이 Macros에 “Downloaded from Marketplace” 태그와 함께 나타납니다.
3. Device Groups에서 그룹을 열고, 기기의 Macro 선택기에서 봇을 고른 뒤 Start를 클릭합니다.
4. 기기 카드의 Logs 탭을 확인합니다. 끝나면 Stop을 클릭합니다.

스크린샷이 포함된 전체 과정은 마켓플레이스에서 매크로 실행하기에 있습니다. 직접 만든 봇을 게시하는 방법은 Marketplace 페이지에서 다룹니다.

MAS Agent에 요청

1. Agent를 열고 Device에서 기기를 고릅니다.
2. 작업을 일상 언어로 설명하고 Author를 클릭합니다.
3. “The agent needs your input” 카드가 나타나면 답합니다. 에이전트는 추측하지 않고 멈춰서 질문합니다.
4. 매크로가 검증 실행 3회를 통과하면 Add to My Macros를 클릭합니다.

결과물은 Code Editor에서 열 수 있는 일반 파이썬 프로젝트입니다. 작성에는 AI 크레딧이 들지만, 완성된 매크로 실행에는 크레딧이 들지 않습니다. 자세한 내용은 MAS Agent 페이지를 참고하세요.

파이썬으로 안드로이드 에뮬레이터 자동화 작성

1. Macros를 열고 Create New Project를 클릭합니다.
2. Code-Based를 선택하고 Target Device를 mobile로 설정한 뒤 프로젝트 이름을 입력하고 Create Project를 클릭합니다.
3. 프로젝트를 엽니다. Code Editor에 src/app.py가 표시됩니다. 아래 스크립트를 붙여 넣습니다.
4. 기기를 고르고 Run(F5)을 클릭합니다. Stop은 Shift+F5, Save는 Ctrl+S입니다.

SDK 개요에서 네임스페이스를 설명하고, API 레퍼런스에 모든 함수가 정리되어 있습니다.

첫 스크립트

이 스크립트는 기기 정보를 읽고, 스크린샷을 찍고, 화면 전체에 OCR을 실행합니다. 기기에서 바뀌는 것은 없습니다.

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는 실행 콘솔에 레벨이 붙은 줄을 씁니다. 일반 print도 동작합니다.

자주 쓰는 패턴

이미지를 찾아 탭하기

Asset Lab에서 버튼을 잘라 Image Library에 ID와 함께 저장한 뒤, mas.images로 선언합니다. find_object_retry는 2초 간격으로 최대 세 번 찾고, 아무것도 맞지 않으면 None을 반환합니다.

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는 기본적으로 임계값 0.8로 매칭합니다. click은 앱이 반응할 수 있도록 탭 후 1000 ms를 기다립니다. 빠른 반복문에서는 delay_ms를 낮추세요.

영역에서 텍스트 읽기

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은 영역을 한 줄로 취급하므로 카운터에 알맞습니다. 좌표를 복사하기 전에 Asset Lab에서 영역을 그리고 실시간으로 테스트하세요.

오류 처리

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

문제 해결

Could not discover RPC port

스크립트가 MAS 밖에서 시작되었거나 앱이 실행 중이 아닙니다. Code Editor나 기기 카드에서 스크립트를 실행하세요. 앱이 연결 정보를 넘겨주며 실행합니다.

클릭한 페이지 대신 Subscription이 열림

이용 권한이 없거나 만료되었습니다. 체험을 시작하거나 요금제를 고른 뒤 돌아오세요. 결제를 참고하세요.

기기를 찾을 수 없거나 Connecting에서 멈춤

에뮬레이터의 ADB가 꺼져 있거나, 에뮬레이터가 아직 부팅 중이거나, 다른 포트를 사용하고 있습니다. ADB 문제 해결을 참고하세요.