Macro com reconhecimento de imagem: como o MAS funciona

O Macro Automation Studio (MAS) automatiza apps Android do jeito que uma pessoa faz: olha para a tela, decide e toca. Esta página explica como uma macro com reconhecimento de imagem funciona, os termos que você encontra no app e onde cada parte roda. Leia uma vez e o resto da documentação vai fazer sentido.

Como uma macro com reconhecimento de imagem vê a tela

O MAS não modifica APKs e não lê a memória dos apps. Ele trabalha de fora, por adb, com três blocos básicos.

Imagens template

Um template é um recorte pequeno da tela: um botão, um ícone, um selo. Você o recorta no Asset Lab a partir do dispositivo ao vivo, ele entra na sua Biblioteca de imagens com um ID numérico, e o seu script se refere a ele por esse ID. Em tempo de execução, find_object tira uma captura de tela nova e procura o template nela com template matching do OpenCV. Uma correspondência precisa de similaridade 0.8 por padrão (threshold=0.8) e retorna o ponto central, então a linha seguinte é um toque.

Os arquivos de imagem podem ser jpg, png, gif ou webp, com até 10 MB cada. Mantenha os templates pequenos e distintos: uma tela inteira só corresponde àquela tela exata, enquanto um botão corresponde onde quer que o botão apareça.

Automação com OCR no Android

O texto é lido com o Tesseract OCR por meio de read_text. Você passa uma Region(x1, y1, x2, y2) para que o motor olhe para um contador ou um rótulo em vez da tela inteira, e um modo de segmentação de página (psm=7 para uma única linha, psm=8 para uma única palavra). ColorConversion.BLACK_WHITE ajuda com texto colorido sobre fundos ruidosos. O Asset Lab tem um teste de OCR ao vivo para você ajustar a região antes de levá-la para o código.

Entrada humanizada

A entrada é enviada como eventos reais de toque e de tecla: click, swipe, input_text, key_press, zoom_in e zoom_out. O tempo é você quem define. Um click espera delay_ms=1000 depois do toque, um swipe leva duration_ms=1000, e uma tecla segurada por 500 ms ou mais conta como toque longo. Macros mais lentas e espaçadas parecem menos mecânicas.

Coordenadas e tamanho da tela

Toda coordenada é um deslocamento em pixels a partir do canto superior esquerdo da tela. get_screen_size() retorna largura e altura; get_device_info() retorna o mesmo mais o nome do dispositivo. Templates e regiões ficam presos à resolução e ao DPI em que foram capturados, então mantenha todo dispositivo que roda uma macro na mesma resolução daquele em que você a construiu. Os guias de emulador recomendam um tamanho para cada emulador, e os dispositivos na nuvem são criados com um preset de tela fixo.

Vocabulário

Onde as coisas rodam

Três lugares fazem o trabalho, e ajuda saber para qual deles você está olhando.

Seu computador controla os emuladores

O MAS no seu computador ou Mac encontra os emuladores pelo nome do processo e pelas portas em que escutam, e então fala com cada um por adb connect 127.0.0.1:<port>. Capturas de tela, toques e OCR de um dispositivo local acontecem todos na sua máquina, então o app precisa ficar aberto enquanto a macro roda. O mesmo vale para o agendador.

Dispositivos na nuvem rodam na nuvem do MAS

Um dispositivo na nuvem vive nos servidores do MAS. Quando você roda uma macro nele, o MAS envia um snapshot do seu projeto e o executa ao lado do dispositivo. Você pode assistir à tela ao vivo no app ou fechar o app por completo; a execução continua de qualquer forma. Dispositivos ociosos param depois de cerca de uma hora sem atividade e mantêm seus dados.

Os scripts falam com o app por JSON-RPC

Uma macro é um processo Python normal. O MAS o inicia como python -u -m src.app dentro do próprio ambiente Python 3.13 e entrega os dados de conexão em variáveis de ambiente (MAS_RPC_PORT, MAS_RPC_HOST, MAS_DEVICE_ID, MAS_SESSION_TOKEN). Toda chamada mas.* é uma requisição JSON-RPC 2.0 por um socket local; o app é dono do adb, do OpenCV e do Tesseract e devolve o resultado. Em um dispositivo na nuvem, as mesmas chamadas viajam por um socket unix dentro do sandbox. É por isso que import mas não precisa de instalação e um script iniciado fora do MAS informa “Could not discover RPC port”.

IA na hora de criar, nenhuma na hora de rodar

O MAS Agent gasta créditos de IA enquanto explora e compila. A macro que ele produz é Python puro e roda como qualquer outra, no seu emulador ou em um dispositivo na nuvem, sem o agente no circuito.

A assinatura

Toda página do app, exceto o login e Assinatura, exige uma assinatura ativa: o teste gratuito ou um plano pago. Um plano é dimensionado por dispositivos, ou seja, quantos dos seus emuladores ou celulares podem rodar ao mesmo tempo. Dispositivos na nuvem são um complemento com créditos mensais próprios, e créditos extras podem ser recarregados para sessões do agente. Cancelar mantém o acesso até o fim do período pago. A página Cobrança explica a mecânica; os valores estão na página de preços.

Para onde ir agora

Configure um dispositivo na página Dispositivos, recorte seu primeiro template no Asset Lab ou leia a visão geral do SDK se preferir começar pelo código.