Pular para o conteúdo

Exemplos

Receitas prontas para copiar e colar nos fluxos de trabalho mais comuns do Clearcote. Comece pela menor que resolva o seu caso e só acrescente opções quando precisar delas.

As receitas aparecem para os SDKs de Python, Node e .NET (pip install clearcote / npm install clearcote / dotnet add package Clearcote). O SDK .NET cobre os fluxos principais — launch, contextos persistentes, serve, proxy, geoip (Geoip = true) e canvas bridge, com input humanizado por meio de chamadas explícitas a HumanClickAsync / HumanTypeAsync em vez de uma flag de launch; perfis salvos, Widevine e o agente embutido no navegador, por enquanto, são só para Python & Node.

Toda receita roda o build aberto, a menos que haja uma chave de licença definida; com uma (clearcote login, CLEARCOTE_LICENSE_KEY ou license_key=), o mesmo código roda o build licenciado mais recente. O plano Grátis com GitHub roda um navegador por vez. Uma coisa que costuma surpreender: o motor nunca repassa eventos de console nem de erro de página, então page.on("console") não recebe nada, por design — colete a saída na página e leia de volta com page.evaluate().

1. Inicie um navegador verificado pelo SDK

O SDK baixa o navegador no primeiro uso e confere o SHA-256 dele — o build aberto por padrão, o build licenciado mais recente quando há uma chave definida. Ele retorna objetos comuns do Playwright, então o resto da sua automação continua familiar. (Desde a versão 0.23, launch() no Python síncrono e no Node roda num perfil descartável e new_context() devolve esse mesmo perfil; passe ephemeral_profile=False / ephemeralProfile: false se precisar de contextos isolados.)

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. Exponha um endpoint CDP stealth para qualquer framework

serve() roda o Clearcote como um endpoint CDP permanente e retorna uma cdp_url. Ele inicia o binário diretamente — sem --enable-automation — e qualquer cliente Playwright, Puppeteer, browser-use, Crawl4AI ou Stagehand se conecta via CDP sem nenhuma mudança no código. Abra as páginas em contexts[0] para usar o perfil servido; new_page() no navegador cria um contexto separado e isolado. Para um agente de IA, aponte o Claude / Cursor / Cline para o servidor clearcote-mcp (pip install clearcote-mcp ou npx -y clearcote-mcp, que exige Python 3.10+). Num shell, clearcote serve roda o mesmo endpoint e pode dar a cada conexão a própria identidade — veja Deploy.

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. Uma identidade estável por conta

Use uma seed determinística e um diretório de user data persistente. A seed mantém estável a identidade do navegador; o diretório do perfil guarda cookies, local storage, permissões e o estado da sessão.

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. Alinhe fuso horário, idioma, localização e WebRTC ao proxy

Com o geoip ativado, o Clearcote descobre o IP de saída do proxy passando pelo próprio proxy e usa um banco de dados GeoIP (baixado no primeiro uso, cerca de 50 MB) para preencher o fuso horário, o idioma, a localização e o endereço WebRTC que você não definiu. Isso evita ter que casar à mão um fuso horário com cada proxy. Se a região não puder ser resolvida dentro de CLEARCOTE_GEOIP_TIMEOUT_SECONDS (padrão 20), o launch para com GeoipError em vez de iniciar com o relógio e o idioma desta máquina; defina timezone e accept_language para iniciar mesmo assim. No .NET, defina Geoip = true.

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. Salve e reutilize um perfil com nome

Um Profile salvo é útil quando você quer uma persona com nome que vários scripts possam compartilhar. Mantenha segredos fora do controle de versão: os arquivos de perfil ficam em texto puro.

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Use o canvas bridge só onde ele faz diferença

O modo bridge pode ser limitado por domínio registrável. O exemplo abaixo passa as leituras de canvas/WebGL pelo bridge só nas origens listadas e usa a renderização local em todo o resto. Preencha as strings de GPU com as da GPU que renderiza (o renderer que o servidor do bridge imprime), para que a GPU informada bata com os pixels que vêm do bridge. Ativar o bridge faz o renderer rodar sem o sandbox do Chromium (o SDK adiciona --no-sandbox para o navegador inteiro, qualquer que seja o modo), então ative o bridge só nas sessões que precisam dele.

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

Inicie o host do bridge antes. Veja Canvas bridge para o comando do servidor, orientações de rede e o comportamento de fallback.

7. Reproduza vídeo com DRM usando Widevine

O Clearcote traz toda a infraestrutura de EME, mas nunca o CDM proprietário do Google. widevine baixa o CDM do Widevine uma única vez do servidor de componentes do Google, verifica, instala no perfil e ativa — assim requestMediaKeySystemAccess('com.widevine.alpha') resolve e os streams com DRM tocam, como num Chrome de verdade.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

Opt-in por design — o pacote nunca distribui o CDM do Google; é você quem dispara o download único (fica em cache em ~/.clearcote/WidevineCdm). Funciona com launch() e launch_persistent_context() no Python síncrono; no Node, use launchPersistentContext() como acima (o tipo TypeScript de launch() ainda não declara widevine). Não funciona com o launch() assíncrono do Python, que é anônimo, nem no .NET. Segurança por software (L3). Um navegador que se apresenta como Google Chrome, mas não consegue responder à consulta do Widevine, é algo que qualquer página consegue perceber, e é por isso que vale ativá-lo. Veja Widevine & DRM.

8. Baixe o navegador com antecedência no CI

Aqueça o cache do navegador verificado antes de a sua suíte de testes começar. Assim as falhas aparecem cedo, antes de os jobs paralelos começarem. Sem chave, isso baixa o build aberto; com CLEARCOTE_LICENSE_KEY definida, baixa o licenciado. Uma chave Grátis com GitHub roda um navegador por vez, então rode os testes de navegador em série ou use o Pro.

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. Rode uma tarefa de agente e guarde o trace

O agente embutido no navegador é opt-in. Dê a ele um diretório de perfil persistente, um endpoint/chave compatível com OpenAI e um número limitado de passos, para que a execução seja reproduzível e revisável.

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. Playwright puro, quando você não quer usar o SDK

O SDK é o caminho mais cômodo, mas o build aberto é um binário normal do Chromium que você pode iniciar diretamente pelo Playwright ou pelo Puppeteer. O build licenciado precisa do SDK — é ele que guarda o token de licença que o motor verifica na inicialização. Os argumentos extras abaixo são os padrões que o SDK, de outra forma, adicionaria por você.

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Comece com uma receita pequena. Só acrescente importação de perfil, canvas bridge, modo agente ou overrides manuais de GPU quando o seu fluxo de trabalho realmente precisar deles.