Como Usar AdsPower com Playwright: Guia Completo de Configuração

AdsPower oferece perfis de navegador isolados e protegidos por fingerprint; Playwright oferece um framework de automação rápido e confiável. Quando você conecta os dois, obtém um fluxo de trabalho que pode gerenciar dezenas de contas, extrair páginas protegidas e executar testes de ponta a ponta em ambientes de navegador realistas sem acionar defesas anti-bot. Este guia percorre toda a configuração, desde habilitar a API Local do AdsPower até escrever scripts em Python e Node.js que controlam perfis através da conexão CDP do Playwright.

Por que Combinar AdsPower e Playwright?

Playwright product interface.

Playwright é construído para automação web moderna. Ele tem espera automática, asserções web-first, localizadores resilientes e suporte nativo para conectar-se a instâncias de navegador existentes através do Chrome DevTools Protocol (CDP). AdsPower expõe exatamente isso: um endpoint WebSocket local para cada perfil iniciado. Ao conectar o Playwright a esse endpoint, você controla uma sessão de navegador totalmente isolada e com fingerprint falsificado como se fosse uma instância Chromium normal.

Essa combinação resolve um conjunto específico de problemas:

• Segurança multi-conta em escala. Cada perfil AdsPower tem seus próprios cookies, cache, fingerprint Canvas/WebGL e proxy. O Playwright os controla sem contaminação cruzada.
• Menos bloqueios durante scraping. Fingerprints anti-detecção mais os padrões de interação realistas do Playwright reduzem a chance de um site alvo sinalizar sua automação.
• Um código, muitas identidades. Você pode percorrer IDs de perfil e executar o mesmo script do Playwright contra centenas de sessões isoladas.
• Sem patches personalizados no navegador. O Playwright fala com o kernel Chromium existente do AdsPower via CDP, então você mantém a tecnologia de fingerprint do AdsPower intacta.

Se você ainda está comparando navegadores anti-detecção antes de se comprometer, veja AdsPower vs Maskfog vs Incogniton: Como Escolher em 2026? para uma análise recurso por recurso.

Pré-requisitos

Antes de escrever qualquer código, certifique-se de ter:

1. AdsPower instalado e em execução no Windows, macOS ou Linux.
2. Pelo menos um perfil de navegador criado no cliente AdsPower. Anote o ID do perfil mostrado na lista de perfis.
3. Python 3.8+ ou Node.js 16+ instalado, dependendo da sua preferência de linguagem.
4. Playwright instalado no seu projeto:

pip install playwright httpx
# ou
npm install playwright axios

1. API Local do AdsPower habilitada. No cliente AdsPower, vá em Configurações > API Local e confirme que o serviço está rodando na porta 50325. Se você usar verificação por chave de API, copie sua chave; caso contrário, você pode desabilitar a verificação apenas para desenvolvimento local.

Entendendo a API Local do AdsPower

A API Local é um serviço HTTP local que o AdsPower executa em http://127.0.0.1:50325. Ela permite iniciar e parar perfis de navegador programaticamente. Os endpoints principais são:

• GET /api/v1/browser/start?user_id={profile_id} — inicia um perfil e retorna detalhes de conexão.
• GET /api/v1/browser/stop?user_id={profile_id} — fecha um perfil.
• POST /api/v2/browser-profile/start — endpoint v2 mais novo com opções adicionais como last_opened_tabs e proxy_detection.

Quando você inicia um perfil, a resposta contém um campo data.ws.puppeteer. Esse é o endpoint WebSocket CDP que o Playwright precisa. A resposta também inclui data.webdriver, que é o caminho para o driver Chrome incluído no AdsPower — útil para Selenium, mas não necessário para Playwright.

Passo 1: Iniciar um Perfil AdsPower via API Local

O primeiro passo do script é sempre iniciar o perfil e capturar o endpoint CDP. Aqui está um exemplo mínimo em Python usando httpx:

import httpx

LOCAL_API_BASE = "http://127.0.0.1:50325"
PROFILE_ID = "seu_id_de_perfil_aqui"
API_KEY = "sua_chave_api_aqui"  # opcional se a verificação da API estiver desabilitada

headers = {"Authorization": f"Bearer {API_KEY}"}

response = httpx.post(
    f"{LOCAL_API_BASE}/api/v2/browser-profile/start",
    headers=headers,
    json={
        "profile_id": PROFILE_ID,
        "last_opened_tabs": "0",
        "proxy_detection": "0",
    },
)

if response.status_code != 200:
    raise RuntimeError(f"Falha ao iniciar o perfil: {response.text}")

data = response.json()
cdp_endpoint = data["data"]["ws"]["puppeteer"]
print(f"Endpoint CDP: {cdp_endpoint}")

A opção last_opened_tabs controla se o AdsPower restaura abas da sessão anterior. Definir como "0" dá a você um início limpo, que é geralmente o que você quer para automação.

Passo 2: Conectar o Playwright ao Perfil

Depois de obter o endpoint CDP, use connect_over_cdp do Playwright para anexar ao navegador em execução:

from playwright.sync_api import sync_playwright

with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(cdp_endpoint)
    default_context = browser.contexts[0]
    page = default_context.pages[0] if default_context.pages else default_context.new_page()

    page.goto("https://www.browserscan.net")
    print(page.title())
    page.wait_for_timeout(10000)

    browser.close()

Para Node.js, o padrão é quase idêntico:

const axios = require('axios');
const { chromium } = require('playwright');

const PROFILE_ID = 'seu_id_de_perfil_aqui';
const API_KEY = 'sua_chave_api_aqui';

axios.get(`http://127.0.0.1:50325/api/v1/browser/start?user_id=${PROFILE_ID}`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
}).then(async (res) => {
  const cdpEndpoint = res.data.data.ws.puppeteer;
  const browser = await chromium.connectOverCDP(cdpEndpoint);
  const defaultContext = browser.contexts()[0];
  const page = await defaultContext.newPage();
  await page.goto('https://www.browserscan.net');
  console.log(await page.title());
  await browser.close();
}).catch((err) => {
  console.error(err.message);
});

Importante: Use o Contexto Existente

Quando você conecta via CDP, o Playwright cria um wrapper ao redor do navegador que o AdsPower já iniciou. Não chame browser.newContext() — isso criaria um contexto novo sem a configuração de fingerprint do AdsPower. Sempre use browser.contexts[0], que representa o contexto de navegação real do perfil com seu proxy, cookies e fingerprint intactos.

Passo 3: Fechar o Perfil Corretamente

Após sua automação terminar, feche o navegador e pare o perfil através da API. Isso libera recursos e garante que o AdsPower salve o estado da sessão corretamente:

browser.close()
httpx.get(
    f"{LOCAL_API_BASE}/api/v1/browser/stop?user_id={PROFILE_ID}",
    headers=headers,
)

Em Node.js:

await browser.close();
await axios.get(`http://127.0.0.1:50325/api/v1/browser/stop?user_id=${PROFILE_ID}`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

Exemplo Completo em Python

Aqui está um script completo que inicia um perfil, navega para um site de verificação de fingerprint, imprime o título da página e encerra tudo:

import httpx
from playwright.sync_api import sync_playwright

LOCAL_API_BASE = "http://127.0.0.1:50325"
PROFILE_ID = "seu_id_de_perfil_aqui"
API_KEY = "sua_chave_api_aqui"

headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Iniciar o perfil AdsPower
resp = httpx.post(
    f"{LOCAL_API_BASE}/api/v2/browser-profile/start",
    headers=headers,
    json={"profile_id": PROFILE_ID, "last_opened_tabs": "0", "proxy_detection": "0"},
)
if resp.status_code != 200:
    raise RuntimeError(f"Falha ao iniciar: {resp.text}")

cdp_endpoint = resp.json()["data"]["ws"]["puppeteer"]

# 2. Conectar o Playwright
with sync_playwright() as playwright:
    browser = playwright.chromium.connect_over_cdp(cdp_endpoint)
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()

    page.goto("https://www.browserscan.net")
    print(f"Título da página: {page.title()}")
    page.wait_for_timeout(8000)

    browser.close()

# 3. Parar o perfil
httpx.get(f"{LOCAL_API_BASE}/api/v1/browser/stop?user_id={PROFILE_ID}", headers=headers)

Escalando para Múltiplos Perfis

Uma das maiores vantagens dessa configuração é percorrer muitos perfis. Mantenha uma lista de IDs de perfil e execute o mesmo fluxo de trabalho contra cada um sequencialmente ou em paralelo:

profile_ids = ["perfil_a", "perfil_b", "perfil_c"]

for pid in profile_ids:
    resp = httpx.post(
        f"{LOCAL_API_BASE}/api/v2/browser-profile/start",
        headers=headers,
        json={"profile_id": pid, "last_opened_tabs": "0", "proxy_detection": "0"},
    )
    cdp_endpoint = resp.json()["data"]["ws"]["puppeteer"]

    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(cdp_endpoint)
        page = browser.contexts[0].pages[0]
        page.goto("https://example.com")
        # Sua lógica por perfil aqui
        browser.close()

    httpx.get(f"{LOCAL_API_BASE}/api/v1/browser/stop?user_id={pid}", headers=headers)

Para scraping de alto volume, combine este loop com a criação de perfis em lote do AdsPower e rotação de proxies. Se você está construindo um pipeline de dados maior, o guia de automação de scraping cobre abordagens baseadas em navegador vs. baseadas em API e como evitar bloqueios em escala.

Casos de Uso Práticos

Gerenciamento de Mídias Sociais Multi-Conta

Execute o mesmo script de postagem ou engajamento contra perfis AdsPower separados, cada um com seu próprio proxy e fingerprint. O Playwright lida com a lógica de interação; o AdsPower mantém as identidades isoladas.

Monitoramento de Preços em E-Commerce

Inicie perfis configurados para diferentes regiões, navegue até sites de varejistas e extraia dados de preços. A diversidade de fingerprints mais proxies residenciais reduz a chance de bloqueios baseados em IP.

Verificação de Anúncios e Teste de Páginas de Destino

Abra campanhas da perspectiva de diferentes perfis de usuário e geolocalizações. Os recursos de screenshot e asserção do Playwright permitem verificar se os anúncios renderizam corretamente para cada segmento de público.

Fluxos de Trabalho com Muitos CAPTCHAs

Quando um site alvo apresenta um CAPTCHA, você pode integrar um solucionador no mesmo script do Playwright. Para um passo a passo completo, veja Como Usar AdsPower com CapSolver.

Solução de Problemas Comuns

Conexão Recusada na Porta 50325

Certifique-se de que o AdsPower está em execução e a API Local está habilitada nas Configurações. Em alguns sistemas, um firewall pode bloquear tráfego localhost — permita a porta 50325 para conexões locais.

connect_over_cdp Expira

Confirme que o endpoint CDP está acessível. Imprima o endpoint e teste-o em um navegador ou com curl. Se o AdsPower iniciou o perfil, mas o WebSocket não está respondendo, reinicie o perfil e tente novamente.

Página em Branco ou Sem Contexto

Se browser.contexts[0] não tiver páginas, crie uma com context.new_page(). Evite chamar browser.newContext() porque isso ignora a configuração de fingerprint do AdsPower.

API Retorna um Código de Erro

Verifique se o ID do perfil está correto e se o perfil não está já em execução. O endpoint de início v1 retorna code: 0 em caso de sucesso; qualquer outro valor indica um problema, geralmente um ID inválido ou um perfil já ativo.

Incompatibilidade de Versão do Playwright

Use uma versão recente do Playwright. O método connect_over_cdp tem sido estável nas versões modernas, mas versões mais antigas podem não ter suporte CDP completo para os recursos mais novos do protocolo Chromium.

AdsPower + Playwright vs. Selenium e Puppeteer

A API Local do AdsPower retorna detalhes de conexão para todas as três principais ferramentas de automação. Por que escolher Playwright?

Recurso	Playwright	Selenium	Puppeteer
Espera automática	Embutida	Esperas manuais	Parcial
Asserções web-first	Sim	Não	Não
Localizadores resilientes	Sim	Limitado	Limitado
Conexão CDP	connect_over_cdp	debuggerAddress	puppeteer.connect
Isolamento de teste paralelo	Contextos nativos	Manual	Parcial
Suporte a múltiplas linguagens	Python, Node.js, Java, .NET	Muitas	Apenas Node.js

A espera automática do Playwright remove a maioria das dores de cabeça de testes instáveis, e sua biblioteca de asserções torna a verificação mais limpa. Para trabalhos de scraping de longa duração onde você precisa de controle máximo sobre a sessão do navegador, Puppeteer é uma alternativa sólida; para equipes já padronizadas em Selenium, AdsPower também suporta isso. Mas para novos projetos de automação, Playwright oferece o melhor equilíbrio entre confiabilidade e experiência do desenvolvedor.

Considerações de Segurança

• Mantenha a verificação da API habilitada em produção. Desabilitá-la significa que qualquer processo local pode controlar seus perfis.
• Armazene chaves de API em variáveis de ambiente, não no código-fonte.
• Use proxies dedicados para cada perfil. AdsPower suporta proxies HTTP, SOCKS5 e SSH — configure-os no nível do perfil para que o Playwright os herde automaticamente.
• Valide a confiança do perfil. Apenas inicie perfis que você mesmo criou, especialmente ao executar scripts de terceiros.

Se você quiser verificar se seu proxy e fingerprint estão funcionando corretamente antes de executar automação em escala, o guia de configuração AdsPower + Whoer.net mostra como verificar vazamentos de IP e fingerprint.

Leitura relacionada

• Tutorial Incogniton: Configurar Perfis, Proxies e Automação - Aprenda Incogniton passo a passo: crie seu primeiro perfil de navegador, adicione proxies, gerencie fingerprints e use a API para fluxos de automação.

Fontes e leitura adicional

• Exemplos de Código - Exemplos de código para automatizar AdsPower com Python, Javascript e Java.Exemplos de código ChromePython Selenium O demo passou no teste na versão selenium 3.141.0 import requests,time from selenium import webdriver fro
• r/Playwright no Reddit: Alguém controlou o navegador AdsPower ... - 7 de outubro de 2024 ... Alguém controlou o navegador AdsPower usando o Playwright do Python? ... Olá. Eu olhei a documentação oficial do AdsPower e não há menção ...
• Servidor MCP LocalAPI AdsPower: Automação de Navegador Mais Inteligente com IA - Descubra como o Servidor MCP LocalAPI AdsPower conecta ferramentas de IA como Claude para automatizar criação, gerenciamento e controle de perfis de navegador — comece a testar hoje.

Perguntas Frequentes

O AdsPower suporta oficialmente o Playwright?

Sim. A documentação oficial da API Local do AdsPower inclui exemplos de Playwright em Python e JavaScript que usam connect_over_cdp com o endpoint ws.puppeteer retornado pela API de início.

Posso usar a API assíncrona do Playwright com AdsPower?

Sim. Substitua sync_playwright() por async_playwright() e use await playwright.chromium.connect_over_cdp(cdp_endpoint). A lógica de conexão é idêntica; apenas a sintaxe difere.

Preciso instalar um Chromium separado para o Playwright?

Não. Quando você conecta via CDP, o Playwright controla a instância Chromium que o AdsPower já iniciou. Você não precisa dos binários de navegador empacotados do Playwright para este fluxo de trabalho.

Posso executar vários perfis AdsPower em paralelo com Playwright?

Sim. Inicie vários perfis através da API Local, colete seus endpoints CDP e conecte-se a cada um. Para Python, use asyncio com async_playwright(); para Node.js, use Promise.all.

O Playwright funciona com perfis baseados em Firefox do AdsPower?

O suporte a Firefox do AdsPower requer uma versão de patch específica e Firefox 123 ou mais novo. O padrão de conexão CDP é projetado para perfis Chromium, então use perfis baseados em Chromium para automação com Playwright.

Qual é a diferença entre os endpoints de início v1 e v2?

O endpoint v2 (/api/v2/browser-profile/start) aceita um corpo JSON com opções extras como last_opened_tabs e proxy_detection. O endpoint v1 usa parâmetros de consulta. Ambos retornam a mesma estrutura de dados de conexão.

Conclusão

Conectar AdsPower ao Playwright é um padrão simples de três etapas: iniciar um perfil através da API Local, anexar o Playwright via connect_over_cdp e parar o perfil quando terminar. Esse loop simples desbloqueia uma combinação poderosa — os primitivos de automação confiáveis do Playwright rodando dentro dos ambientes de navegador isolados e protegidos por fingerprint do AdsPower. Seja gerenciando dezenas de contas sociais, extraindo preços de concorrentes ou verificando anúncios em regiões, essa integração dá a você o controle e a segurança para escalar sem acionar sistemas anti-bot.

Comece com um perfil, verifique seu script contra um site de verificação de fingerprint como BrowserScan e depois expanda para loops multi-perfil com proxies. Uma vez que o padrão está no lugar, você pode aplicá-lo a quase qualquer fluxo de trabalho de automação web que exija identidades de navegador realistas e isoladas.