Opções e identidades
O que você pode definir ao iniciar um navegador hospedado: as opções, os padrões de stealth e as identidades, perfis que mantêm você logado, uma versão fixada e a página inicial.
Opções
Todas são opcionais. Envie-as como corpo JSON da chamada de criação.
| Campo | Tipo | Significado |
|---|---|---|
identity | string | One label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online. |
fingerprint | string | Device seed only (no IP pinning). The same seed gives the same device profile every time; with lightStealth on it picks from a small set of metadata profiles. |
lightStealth | boolean | Default true: varies only the metadata axes the host can back up. Set false to turn it off. |
platform | windows | Always windows: the browsers run on Windows machines, and a persona of another system there reports GPU limits and fonts no such machine has. Another value starts a Windows session and warnings says so. |
brand | Chrome | Edge | Opera | Vivaldi | Browser brand the persona presents. |
timezone | IANA name | e.g. America/New_York. Omitted = the exit IP's. Given, it is kept as you wrote it and checked against the exit IP: under geoIdentity "strict" (the default) a time zone the exit's country does not use refuses the launch. |
locale | string | Accept-Language, e.g. en-US,en. Omitted = a language of the exit IP's country. Given, it is kept and checked against the exit like timezone. |
geoIdentity | "strict" | "warn" | "auto" | "manual" | "off" | { mode?, acknowledge?, localePolicy? } | Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event. |
geoip | boolean | Older option, read only when geoIdentity is not set: true = geoIdentity "auto", false = "manual". |
proxy | "managed" | { server, username?, password? } | Omitted = managed residential pool. Or your own proxy: http://, socks5:// or socks5h:// (rules below). |
country | 2-letter code | Managed pool: exit country, e.g. us, de, gb. |
state | region code | Managed pool: exit state/region, e.g. ca, ny. Needs country. |
city | city name | Managed pool: exit city, e.g. "los angeles". Needs state. |
proxySession | string | Managed pool: sticky label. The same label returns the same exit IP later (kept for 24 hours). |
timeoutSec | number | Hard limit on the session length, in seconds (10 up to the account maximum below). |
idleTimeoutSec | number | End the session after this long without a CDP command (10–1800). |
maxGb | number | Stop the session after this much traffic (0.001–1000). |
headless | boolean | Default true. With false the browser opens a real window on the server. Under the default lightStealth, the page then reports that server's own display (its whole screen, with the window maximized) instead of your identity's screen size; the identity still sets CPU cores, memory, colour depth and pixel ratio. Keep the default when the identity's screen should apply. |
humanize | boolean | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input". |
keepAlive | boolean | Default false. Keep the browser running when your client disconnects, until you end it (DELETE, or the CDP command Browser.close) or a limit does; reconnect with POST /api/v1/browsers/<id>/connect. |
version | string | Run a specific Clearcote release, e.g. "152.0.7977.82-r21" or "r21". Omitted = the current release. See "Pinning a release". |
profile | "name" | { name, persist? } | Load a saved profile (cookies + site storage). With persist: true, save it back when the session ends. See "Profiles". |
url | http(s) URL | Opened in the first tab before you connect: you find it already loading. |
adblock | boolean | Refuse known ad and tracker hosts before they load, so they are never billed. Default false. |
solveSliders | boolean | Default true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges". |
solveCheckboxes | boolean | Default true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges". |
solvePressHold | boolean | Default true. "Press and hold" verification buttons are held for you until they report done, in any tab or frame; false leaves them to your script. See "Press-and-hold challenges". |
challengeService | true | { categories?, sites?, key?, apiKey?, mode?, maxSolves?, maxSpendEur? } | Default off. Challenges the free actions cannot clear go to a solving service, with your own key or ours (billed per solve). true (or no categories) auto-selects: every challenge it recognises, in token, clearance, block-page and image; or list categories and sites yourself. See "Challenge service". |
record | boolean | Default false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days). |
note | string | Your label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list. |
worker | string | Place the session on the same server as an earlier one (its worker). If that server is full or offline, it starts on another one and warnings says so. |
Padrões de stealth e identidades
Toda sessão parte das configurações da página de configurações recomendadas: uma persona Windows (os navegadores rodam em máquinas Windows, então esse é o sistema que eles conseguem sustentar), lightStealth ativado, uma seed, fuso horário e idioma que acompanham o IP de saída com o seu próprio proxy ou com o nosso, o módulo Widevine que um Google Chrome tem (para que requestMediaKeySystemAccess("com.widevine.alpha") funcione) e movimento humano do mouse (veja abaixo). Com lightStealth (o padrão), a seed escolhe o perfil de dispositivo dentro de um conjunto pequeno que varia núcleos de CPU, memória e pixel ratio; canvas, WebGL e áudio são renderizados pela máquina em que a sessão roda. A placa de vídeo que uma sessão reporta ao WebGL é sorteada para cada sessão entre uma gama de modelos reais da mesma classe que a dessa máquina, e a mesma identity reporta a mesma placa, então sessões numa mesma máquina reportam placas diferentes enquanto os limites do WebGL e as respostas sobre codecs de vídeo continuam coerentes com elas. Defina lightStealth: false para ter uma persona completa por seed: as leituras de canvas e WebGL recebem ruído por site derivado da seed, e as strings de GPU, a tela e as configurações de áudio (taxa de amostragem, latência) seguem a persona. Sem identity nem fingerprint, cada sessão recebe uma seed aleatória e um IP novo.
Passe identity: "account-42" para voltar em sessões futuras com o mesmo perfil de dispositivo e no mesmo IP, enquanto esse IP residencial continuar online, que é o que uma conta logada espera. As identidades são privadas da sua conta: outro cliente que use o mesmo rótulo recebe a própria seed e o próprio IP. Sozinha, uma identidade não guarda cookies: para isso, use um perfil.
Entrada humanizada
O Playwright e o Puppeteer, de fábrica, movem o mouse em um salto só: um único movimento cai no alvo e o clique vem um ou dois milissegundos depois. Um navegador hospedado suaviza isso no servidor, ao lado do navegador, para qualquer cliente: quando um movimento ou um clique cai longe de onde o cursor está, o servidor primeiro leva o cursor até lá do jeito que uma mão faria (em curva, com a velocidade e as pequenas correções de um gesto real) e depois entrega o seu evento. O botão só é pressionado um instante depois que o cursor chega, como uma mão que se acomoda, e cada clique fica pressionado pelo tempo de um toque humano antes de ser solto. Uma identidade mantém um único jeito de se mover. Seu script não precisa de nenhuma mudança e fica cerca de um segundo mais lento por clique.
A rolagem recebe o mesmo tratamento. Uma rolagem de mais de um passo da roda do mouse (100 px nas máquinas Windows em que os navegadores rodam) chega em passos inteiros, em rajadas curtas, como um dedo girando a roda, depois que o cursor vai até o ponto da rolagem, se estava em outro lugar. A página rola exatamente a distância que você pediu, o último passo leva o restante, e a sua chamada retorna quando esse passo sai.
Ficam exatamente como você os envia: movimentos de poucos pixels (um cliente que já se move em passos pequenos, como o próprio humanize do SDK), arrastos com um botão pressionado, uma rolagem de um passo da roda ou menos, o toque e o teclado. Passe humanize: false quando precisar da velocidade original.
Perfis: faça login uma vez só
Um perfil guarda os cookies, o localStorage e o IndexedDB de uma sessão sob um nome, para que a próxima sessão com esse nome já comece logada. Passe profile: { name: "shop-account", persist: true } para carregá-lo e salvá-lo de volta quando a sessão terminar, ou apenas profile: "shop-account" para carregá-lo em modo somente leitura. A primeira sessão com um nome novo começa vazia e cria o perfil.
// Every run: the same body. The first one starts signed out; sign in, then close the browser
// and the session saves the cookies and site storage. Every later run starts signed in.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
method: "POST",
headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
body: JSON.stringify({ profile: { name: "shop-account", persist: true }, country: "de" }),
});- Mesmo dispositivo, mesmo IP. Um perfil traz a própria identidade (
profile:<name>), então o site vê o mesmo fingerprint e, enquanto esse IP continuar online, o mesmo IP residencial, como um cliente que volta. Passeidentityoufingerprintvocê mesmo para escolher outra coisa, e mantenha o mesmo país entre as execuções. - Só uma sessão grava por vez. Apenas uma sessão em execução pode salvar num perfil; uma segunda com
persist: truerecebe409 PROFILE_IN_USE. Sessões somente leitura podem rodar em paralelo e veem o último estado salvo. - Salvo quando a sessão termina, seja porque você fechou o navegador, desconectou ou parou a sessão, seja porque um limite a encerrou. Se o navegador tiver travado, o estado salvo anterior é mantido em vez de ser substituído por um parcial. Cookies de sessão (os que não têm data de expiração) são descartados, como um navegador de verdade faz ao reiniciar.
- Até cerca de 3,5 MB comprimido. Se o IndexedDB de um site passar disso, o IndexedDB fica de fora; cookies e localStorage continuam sendo salvos.
- Privado. Um perfil é só seu (o “shop-account” de outro cliente é outro perfil), fica armazenado criptografado e só é entregue ao servidor que roda a sua sessão. Liste os perfis com
GET /api/v1/browsers/profiles, apague um comDELETE /api/v1/browsers/profiles/<name>ou use o painel.
Já fez login em outro lugar? A sincronização de cookies copia esses cookies para um perfil, então a primeira sessão também começa logada.
Fixando uma versão
As sessões rodam a versão atual do Clearcote. Para rodar uma mais antiga, passe version: a versão completa ("156.0.8078.47-r51"), só o rebuild ("r51"), uma versão ou major do Chromium ("155" pega o build mais recente dela) ou "latest". São as mesmas versões que a opção version do SDK baixa, então uma sessão hospedada e uma execução local fixadas na mesma versão usam o mesmo build.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
method: "POST",
headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
body: JSON.stringify({ identity: "account-1", version: "156.0.8078.47-r51" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine -> { version: "156.0.8078.47", revision: "r51", pinned: true }
// warnings -> [ "This session runs 156.0.8078.47-r51, older than the current ... " ]- Confira os
warnings. Uma versão mais antiga não tem o que as posteriores adicionaram. Opções e correções que vieram depois dela podem estar ausentes, ou ser ignoradas em silêncio em vez de rejeitadas, então uma configuração que funciona na versão atual pode simplesmente não fazer nada numa versão fixada. - O
engineda resposta sempre informa qual versão a sessão roda, fixada ou não. - Uma versão que não existe resulta em
400com o códigoUNKNOWN_VERSION, e a mensagem lista as versões que você pode escolher. - A primeira sessão numa versão que os nossos servidores ainda não usaram pode levar até um minuto a mais para iniciar, enquanto o build é baixado. As sessões seguintes nessa versão iniciam tão rápido quanto qualquer outra.
Página inicial e bloqueio de anúncios
urlabre uma página na primeira aba antes de você se conectar, então ela já está carregando quando o seu script se conecta.adblock: truerecusa requisições para hosts conhecidos de anúncios, de verificação de anúncios e de analytics antes que elas sejam feitas, então elas nunca são cobradas. A lista é conservadora de propósito (gerenciadores de tags, ferramentas de consentimento, SDKs de login e CAPTCHAs ficam de fora), mas alguns sites percebem a falta dos anúncios; deixe desativado onde isso importar.