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.

Padrões de stealth e identidades

Toda sessão parte das configurações da página de configurações recomendadas: lightStealth ativado, uma seed, e fuso horário e idioma que acompanham o IP de saída. 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 os da máquina em que a sessão roda. 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.

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. Passe identity ou fingerprint você 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: true recebe 409 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 com DELETE /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 ("152.0.7977.82-r21"), só o rebuild ("r21"), uma versão ou major do Chromium ("152" 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: "152.0.7977.82-r21" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "152.0.7977.82", revision: "r21", pinned: true }
// warnings -> [ "This session runs 152.0.7977.82-r21, 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 engine da resposta sempre informa qual versão a sessão roda, fixada ou não.
• Uma versão que não existe resulta em 400 com o código UNKNOWN_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

• url abre uma página na primeira aba antes de você se conectar, então ela já está carregando quando o seu script se conecta.
• adblock: true recusa 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.