Automação Android com Python: primeiros passos

A automação Android com Python no Macro Automation Studio (MAS) funciona pela tela: o app olha para um dispositivo, encontra o que precisa e toca. Esta página leva você de uma instalação nova até sua primeira macro Python rodando em um emulador Android, em um dispositivo na nuvem ou no seu celular. Ela é para quem usa o MAS pela primeira vez, no Windows ou no Mac.

Antes de começar

• O MAS está instalado e você fez login. Veja Instalar o MAS.
• Você tem onde automatizar: um emulador Android neste computador, um dispositivo na nuvem ou o seu próprio celular. Veja Dispositivos.
• Sua conta tem uma assinatura ativa ou o teste gratuito. Toda página do app, exceto o login e Assinatura, exige uma. Sem ela, o MAS abre Assinatura e para ali. Os planos estão na página de preços.

Configuração do Macro Automation Studio: escolha um dispositivo

Uma execução tem um dispositivo como alvo. Escolha o tipo que se encaixa:

Para adicionar um emulador:

1. Inicie o emulador e ative o ADB nas configurações dele. Cada guia de emulador mostra onde fica a opção.
2. No MAS, abra Grupos de dispositivos e clique em Criar novo grupo. Mantenha o tipo Local.
3. Abra o grupo e clique em Adicionar dispositivo.
4. Digite um Nome do dispositivo e escolha a porta do emulador na lista Porta. Clique em Atualizar se a lista estiver vazia.
5. Clique em Adicionar dispositivo.

Dispositivos na nuvem são criados na página Dispositivos na nuvem com Criar e aparecem como alvos de execução ao lado dos dispositivos locais. O caminho do celular está descrito na página Dispositivos.

Três formas de conseguir uma macro

Rodar um bot do Marketplace

1. Abra o Marketplace e pesquise o app ou o jogo.
2. Abra uma listagem e clique em Baixar. O bot aparece em Macros, marcado como “Baixado do Marketplace”.
3. Em Grupos de dispositivos, abra o seu grupo, escolha o bot no seletor Macro do dispositivo e clique em Iniciar.
4. Acompanhe a aba Logs do card do dispositivo. Clique em Parar quando terminar.

O passo a passo completo com capturas de tela está em Como rodar uma macro do Marketplace. Publicar o seu próprio bot é assunto da página Marketplace.

Pedir ao MAS Agent

1. Abra Agent e escolha um dispositivo em Dispositivo.
2. Descreva a tarefa com suas palavras e clique em Gerar.
3. Responda quando o card O agente precisa da sua resposta aparecer. O agente para e pergunta em vez de adivinhar.
4. Quando a macro passar em 3 execuções de validação, clique em Adicionar às minhas macros.

O resultado é um projeto Python normal, que você pode abrir no Code Editor. Gerar a macro consome créditos de IA; rodar a macro pronta não consome nenhum. Leia mais na página MAS Agent.

Escrever a automação Android com Python

1. Abra Macros e clique em Criar novo projeto.
2. Escolha Baseado em código, defina Dispositivo alvo como mobile, dê um nome ao projeto e clique em Criar projeto.
3. Abra o projeto. O Code Editor mostra src/app.py. Cole o script abaixo.
4. Escolha o seu dispositivo e clique em Executar (F5). Parar é Shift+F5 e Salvar é Ctrl+S.

A visão geral do SDK explica os namespaces; a referência da API lista todas as funções.

Seu primeiro script

Este script lê o dispositivo, tira uma captura de tela e roda OCR na tela inteira. Nada muda no dispositivo.

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 escreve uma linha com nível no console de execução. Um print comum também funciona.

Padrões comuns

Encontrar uma imagem e tocar nela

Recorte o botão no Asset Lab para que ele entre na sua Biblioteca de imagens com um ID, depois declare-o com mas.images. find_object_retry procura até três vezes, com dois segundos de intervalo, e retorna None quando nada corresponde.

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 compara com um limiar de 0.8 por padrão. click espera 1000 ms depois do toque para o app reagir; reduza delay_ms em loops apertados.

Ler texto de uma região

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 trata a região como uma única linha, o que serve bem para contadores. Desenhe a região no Asset Lab e teste ao vivo antes de copiar as coordenadas.

Tratar erros

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

Solução de problemas

Could not discover RPC port

O script foi iniciado fora do MAS, ou o app não está aberto. Rode os scripts pelo Code Editor ou por um card de dispositivo; o app os inicia com os dados de conexão.

O app abre Assinatura em vez da página que cliquei

Sua assinatura está faltando ou expirou. Inicie o teste ou escolha um plano e volte. Veja Cobrança.

Dispositivo não encontrado ou parado em Conectando

O ADB do emulador está desligado, o emulador ainda está iniciando ou ele escuta em outra porta. Veja Solução de problemas de ADB.