Desafios
Os navegadores hospedados cuidam sozinhos dos desafios de slider, de caixa de seleção e de manter pressionado. O serviço de resolução de desafios, desativado a menos que você o ative, trata os que eles não conseguem.
Desafios de slider
Alguns sites respondem com um desafio do tipo "deslize para verificar": uma alça para arrastar até o fim de uma barra, ou uma peça de quebra-cabeça para arrastar até o seu encaixe. Um navegador hospedado cuida disso para você, em qualquer aba e também dentro de frames. Vem ativado por padrão; passe solveSliders: false quando o seu script cuidar disso sozinho.
- O que ele faz. Um slider simples é arrastado até o fim. Um quebra-cabeça é arrastado até a peça ficar no encaixe: o navegador encontra o encaixe na imagem, confere onde a peça realmente parou e corrige. O arraste é um movimento do mouse com o botão pressionado, em ritmo humano, não um salto.
- Quando ele se segura. Se não encontra o encaixe com confiança, deixa o quebra-cabeça como está em vez de chutar, porque um arraste errado pode contar contra a sessão. Ele tenta no máximo três vezes por página e espera enquanto alguém controla a sessão pela visualização ao vivo ou durante uma transferência.
- O que você vê. Cada tentativa é um evento
sliderna linha do tempo de eventos da sessão, dizendo se o desafio sumiu depois (passed) ou não (failed), ou por que um quebra-cabeça foi deixado como estava (skipped). - Só desafios são tocados: um slider conta como desafio quando a página ou o widget em volta diz isso (um captcha ou uma verificação). Inputs de intervalo, carrosséis e filtros de preço ficam intactos. A entrada de mouse do seu próprio script e um arraste em andamento podem se misturar, então pause os cliques enquanto houver um desafio na tela, ou desative a opção.
Desafios de caixa de seleção
Alguns sites pedem primeiro para marcar uma caixa de "verifique que você é humano". Um navegador hospedado marca para você, em qualquer aba e também dentro de frames, inclusive em widgets que escondem a caixa dos scripts da página. É uma opção separada da dos sliders, também ativada por padrão; passe solveCheckboxes: false para cuidar dessas caixas você mesmo.
- Quais caixas. Só uma caixa cujo próprio texto diz que é uma verificação humana (humano, robô, captcha, verifique que você…). Uma caixa de "lembrar de mim" ou "aceito os termos" nunca é clicada, não importa o que mais a página diga.
- O clique. Um movimento do ponteiro em ritmo humano até a caixa, uma pausa curta e um clique pressionado pelo tempo de uma pessoa. Se a caixa abrir um slider em seguida, ele é tratado como slider.
- O que você vê. Cada tentativa é um evento
checkboxna linha do tempo de eventos da sessão:passedquando a caixa sumiu ou foi marcada,failedquando ainda estava esperando. No máximo três tentativas por página, e nenhuma enquanto alguém controla a sessão pela visualização ao vivo ou durante uma transferência.
Desafios de manter pressionado
Alguns sites mostram um botão de verificação de “manter pressionado”: a verificação passa quando o botão fica pressionado por tempo suficiente. Um navegador hospedado pressiona e mantém o botão para você, em qualquer aba e dentro de frames, inclusive frames de outro site e widgets que escondem o botão dos scripts da página. É uma opção própria, separada dos sliders e das caixas de seleção e também ativada por padrão; passe solvePressHold: false para deixar esses botões para o seu script, por exemplo com manter pressionado. Um navegador que você mesmo executa nunca faz isso por conta própria.
- O pressionar. Um movimento do ponteiro em ritmo humano até o botão, uma pausa curta, depois um clique mantido até o botão indicar que terminou, e uma liberação após um atraso humano.
- O que você vê. Cada tentativa é um evento
pressHoldna linha do tempo de eventos da sessão:passedquando o botão indicou que terminou,failedquando não (um clique mantido que ficou sem tempo tem o motivotimeout), ouskippedcom um motivo. - Em que ordem. Primeiro os sliders, depois as caixas de seleção, depois os botões de manter pressionado. Cada um tem sua própria chave, então desligar um deixa os outros ligados.
Serviço de resolução de desafios
Para sites que continuam apresentando desafios depois das ações gratuitas de slider e de caixa de seleção, um navegador hospedado pode repassar os desafios mais difíceis a um serviço de resolução. Ele fica desativado a menos que você peça: passe challengeService: true para deixar que ele escolha sozinho, ou um objeto para escolher o que ele pode fazer. Ele usa a sua própria chave do serviço de resolução, ou a nossa (cobrada por desafio resolvido; veja quanto custa).
Escolhendo quais desafios ele trata
Você nunca diz a ele qual widget ou qual fornecedor um site usa. O navegador hospedado reconhece sozinho cada desafio na página, pela marcação, pelos frames e pelo comportamento dele, e o classifica em uma de cinco categorias. Você escolhe categorias, não widgets.
| Categoria | O que conta como uma | No auto |
|---|---|---|
token | Um widget que entrega um token à página: uma caixa de "Não sou um robô" que vira um quebra-cabeça de imagens, um widget invisível cujo quebra-cabeça aparece, uma verificação interativa do tipo "confirme que você é humano" que continua sem resposta. | Sim |
clearance | Uma espera de página inteira do tipo "verificando seu navegador" que não se resolve sozinha. | Sim |
block-page | A página de bloqueio de um site com um quebra-cabeça ou uma verificação do dispositivo. | Sim |
image | Um código de texto distorcido ao lado de uma caixa de texto, e um quebra-cabeça cujo encaixe o navegador não conseguiu encontrar sozinho. | Sim |
score | Uma verificação de pontuação invisível que a própria página executa. | Não: inclua na lista você mesmo |
- Seleção automática.
challengeService: true, ou um objeto semcategories(ou comcategories: "auto"): todo desafio que ele reconhece emtoken,clearance,block-pageeimageé tratado, em todos os sites.scorefica de fora porque o navegador já obtém o próprio token de pontuação: respondê-lo por outro meio custa uma resolução a cada chamada, então só vale a pena para um site que rejeite as pontuações das suas sessões. - Escolha categorias.
categories: ["token", "image"]trata só essas. Um desafio de outra categoria continua sendo reportado na linha do tempo (comocategory_off), e nunca é pago. - Escolha sites.
sites: ["shop.example"]limita a atuação a esses hosts e aos subdomínios deles; nos outros sites nada é reportado nem pedido. Combine comcategoriespara "esse tipo de desafio naquele site". - Não sabe o que um site usa? Execute uma vez com
mode: "report": nada é pedido nem pago, e a linha do tempo lista cada desafio que as páginas mostraram comochallenge.detected, com acategorydele e se ele pode ser resolvido. Depois ative exatamente essas categorias para esse site.
// In the body of POST /api/v1/browsers, or in the SDK's launch options (cloud: true)
// Auto-select: every challenge it recognises (all categories but score), on every site
challengeService: true
// Only widgets that hand out a token, only on one site, at most EUR 0.20 per session
challengeService: { categories: ["token"], sites: ["shop.example"], maxSpendEur: 0.2 }
// Only full-page waits and block pages, with your own solving-service key
challengeService: { categories: ["clearance", "block-page"], key: "own" }
// Auto-select plus the score check, on one site
challengeService: { categories: ["token", "clearance", "block-page", "image", "score"], sites: ["shop.example"] }
// First find out what a site uses: report only, nothing asked or paid for
challengeService: { mode: "report" }Todos os campos
| Campo | Tipo | Padrão | Significado |
|---|---|---|---|
categories | "auto" ou uma lista de token, score, clearance, block-page, image | "auto" | Quais tipos de desafio podem ser respondidos. auto inclui todas menos score. |
sites | lista de nomes de host | todos os sites | Só nesses hosts e nos subdomínios deles (no máximo 50). |
key | "own" ou "managed" | a sua chave salva, se tiver uma; senão, a nossa | De quem é a chave do serviço de resolução: a sua ou a nossa (cobrada por desafio resolvido). |
apiKey | string | nenhuma | A sua chave do serviço de resolução só para esta sessão (armazenada criptografada, nunca exibida de novo). Implica key: "own". |
mode | "solve" ou "report" | "solve" | report só reconhece e reporta; nada é pedido nem pago, e nenhuma chave é necessária. |
maxSolves | número inteiro, de 1 a 100 | 10 | Pedidos por sessão; os pedidos param ao chegar a esse número. |
maxSpendEur | número, de 0.01 a 100 | 0.50 | Quanto uma sessão pode gastar em resoluções (com a nossa chave, o que você paga); os pedidos param aí. |
Como funciona
- O gratuito primeiro. As ações de slider e de caixa de seleção sempre vêm primeiro. O serviço só é acionado quando um desafio continua lá depois de ter tido uma chance justa: apareceu um quebra-cabeça de imagens, um widget invisível abriu o seu quebra-cabeça, um widget ficou sem resposta por cerca de 15 a 25 segundos, uma espera de página inteira não se resolveu em cerca de 20 segundos, ou a página é uma página de bloqueio ou um código de texto.
- Como a resposta entra. Do jeito que a página espera: um token no campo de resposta do widget e no seu callback, um cookie para o site e um recarregamento, um código digitado na sua caixa, uma peça de quebra-cabeça arrastada até o lugar. Depois ele verifica se o desafio sumiu, como as ações gratuitas.
- O mesmo IP. Esperas de página inteira e páginas de bloqueio precisam ser resolvidas a partir do IP que usa a resposta: o serviço as resolve pelo próprio IP de saída da sua sessão, por uma conexão de curta duração e de uso único. Um token que o site rejeita é pedido mais uma vez da mesma forma.
- A sua chave ou a nossa.
key: "own"usa a sua chave do serviço de resolução: salve-a uma vez no painel (Settings), ou passeapiKeycom a requisição. Ela é armazenada criptografada, nunca é exibida de novo e nunca chega ao navegador; você paga o serviço diretamente.key: "managed"usa a nossa: cada desafio resolvido é cobrado do seu saldo de navegadores hospedados pelo preço do próprio serviço × 1.5, e tentativas que falham são gratuitas (veja quanto custa). Omitakeypara usar a sua chave salva, se tiver uma, ou a nossa, se não tiver. - Limites. No máximo 2 pedidos por desafio por página. Por sessão,
maxSolves(padrão 10, no máximo 100) emaxSpendEur(padrão €0.50): os pedidos param ao atingir qualquer um dos dois. Com a nossa chave, há também um teto mensal por conta (defina no painel, no máximo €25). Uma chave errada ou saldo zerado no serviço interrompe os pedidos naquela sessão. - O que você vê.
challenge.detecteduma vez por desafio por página, echallenge.servicepara cada pedido (solved,failedouskipped, com o motivo e o custo no serviço) na linha do tempo de eventos;challenges(de quem é a chave, quantos pedidos, quanto custaram as resoluções com a nossa chave) na sessão. Em uma execução de agente, o agente espera enquanto o serviço trabalha em uma página. - Alguns widgets são detectados, mas não resolvidos: a resposta deles não pode ser devolvida a uma página de forma genérica. Eles são reportados com
solvable: falsee nunca são cobrados. O endereço da página e os detalhes do desafio vão para o serviço de resolução.
Quanto custa
- Com a sua própria chave: nada da nossa parte. Você paga o serviço de resolução diretamente, pelo preço dele; o seu saldo de navegadores hospedados só é cobrado pelo tráfego, como em qualquer sessão.
- Com a nossa chave: por desafio resolvido, do seu saldo de navegadores hospedados. O preço do serviço de resolução para aquele desafio (em USD), convertido a 0.92 € por $ e × 1.5. Tentativas que falham, desafios ignorados e
mode: "report"não custam nada. Não há mensalidade nem cadastro. - O preço exato só é conhecido depois que um desafio é resolvido. Ele depende do tipo de desafio, e o serviço envia cada um ao mais barato entre vários solvers capazes de resolvê-lo. Abaixo está a nossa melhor estimativa por tipo, como cobrada com a nossa chave. Normalmente é o preço do solver mais barato, que é o que as nossas resoluções custaram até agora. No máximo é o solver mais caro que o serviço lista para aquele tipo, para quando o mais barato não puder resolvê-lo.
| Na página | Categoria | Normalmente, por 1.000 | Normalmente, por resolução | No máximo, por 1.000 |
|---|---|---|---|---|
| “I’m not a robot” box with a picture puzzle (the most common widget) | token | €0.18 | €0.00018 | €4.13 |
| The same widget’s enterprise edition | token | €0.18 | €0.00018 | €6.90 |
| Interactive “verify you are human” check | token | €0.14 | €0.00014 | €2.76 |
| Other picture-puzzle widgets, visible or invisible | token | €0.95 | €0.00095 | €9.66 |
| Their enterprise editions | token | €2.76 | €0.0028 | €13.80 |
| Smaller token widgets (proof-of-work, puzzle and regional widgets) | token | €1.10 | €0.0011 | €4.14 |
| Invisible score check, standard or enterprise | score | €0.72 | €0.00072 | €6.90 |
| Full-page “checking your browser” wait | clearance | €0.28 | €0.00028 | €1.79 |
| Block page with a slider or a device check | block-page | €0.83 | €0.00083 | €3.81 |
| Block page with a puzzle from a cloud firewall | block-page | €0.69 | €0.00069 | €2.76 |
| Distorted-text code | image | €0.14 | €0.00014 | €0.55 |
| Jigsaw whose gap the browser could not place | image | €1.66 | €0.0017 | €2.76 |
- Na prática. 1.000 resoluções do widget mais comum normalmente saem por cerca de €0.18; o mesmo número de esperas de página inteira, cerca de €0.28. Um token que o site rejeita é pedido mais uma vez pelo IP da sua sessão, então um desafio pode ser cobrado duas vezes, nunca mais que isso.
- Os preços são a tabela do serviço em 2026-10-13 e mudam quando ele os muda. Alguns dos solvers dele cobram conforme a dificuldade do desafio; no máximo usa o topo da faixa deles.
- O custo exato de cada resolução está no evento
challenge.servicedela (costUsd, o preço do serviço antes da conversão e da margem), e ochallenges.costEurda sessão (emGET /api/v1/browsers/<id>) é o total que foi cobrado por elas. - Quanto uma sessão pode gastar no máximo. Os padrões param uma sessão depois de 10 pedidos ou €0.50, o que vier primeiro: 10 resoluções normalmente custam menos de €0.03, e mesmo no preço mais caro acima, cerca de €0.14. Aumente ou diminua esses limites com
maxSolvesemaxSpendEur; o limite mensal por conta (no máximo €25) vale para todas as sessões juntas.
O que acontece com cada tipo
| Na página | Categoria | O que se pede ao serviço | Como a resposta entra |
|---|---|---|---|
| Uma caixa de "Não sou um robô" cujo clique abriu um quebra-cabeça de imagens | token | Um token para esse widget | No campo de resposta do widget, e o callback da página é chamado com ele |
| Um widget invisível cujo quebra-cabeça de imagens apareceu | token | Um token para esse widget | Do mesmo jeito |
| Uma verificação interativa do tipo "confirme que você é humano" que continua sem resposta | token | Um token para esse widget | Do mesmo jeito |
| Um código de texto distorcido ao lado de uma caixa de texto | image | O texto da imagem | Digitado na caixa, tecla por tecla, depois de um clique nela |
| Um slider de quebra-cabeça que o navegador não consegue encaixar sozinho (por exemplo, um com um encaixe falso como isca) | image | Onde está o encaixe | O navegador arrasta a peça até lá, verificando onde ela realmente foi parar |
| Uma espera de página inteira do tipo "verificando seu navegador" que não se resolve | clearance | Um cookie de clearance, resolvido pelo IP de saída da sua sessão | Definido para o site, e então a página recarrega |
| Uma página de bloqueio com um quebra-cabeça ou uma verificação do dispositivo | block-page | Um cookie, resolvido pelo IP de saída da sua sessão | Definido para o site, e então a página recarrega |
Uma verificação de pontuação invisível que a própria página executa (só com score na lista) | score | Um token de pontuação para a ação da própria página | Entregue à chamada que a própria página faz para pedir um token |
As ações gratuitas continuam vindo primeiro: um slider simples é arrastado, um quebra-cabeça cujo encaixe o navegador consegue encontrar é posicionado, e uma caixa que se marca com um clique é clicada, tudo sem acionar o serviço. No widget, a própria caixa pode continuar desmarcada depois que um token entrou: a página lê o campo de resposta e o callback, não a caixa.
Pelos SDKs
O SDK 0.38.0 ou mais recente aceita a opção ao iniciar na nuvem (Python: challenge_service, que também aceita max_solves, max_spend_eur e api_key). A linha do tempo mostra o que aconteceu; os últimos eventos dela chegam alguns segundos depois que a sessão termina.
import { Cloud, launch } from "clearcote";
const browser = await launch({
cloud: true,
challengeService: { categories: ["token", "image"], sites: ["shop.example"], maxSpendEur: 0.2 },
});
const page = await browser.newPage();
await page.goto("https://shop.example/signup");
// ... your script: challenges the free actions cannot clear are answered for you
const id = browser.cloudSession.id;
await browser.close();
const { events } = await new Cloud().browsers.events(id);
for (const e of events) if (e.type.startsWith("challenge.")) console.log(e.type, e.data);
// challenge.detected { category: "token", solvable: true }
// challenge.service { category: "token", outcome: "solved", applied: "callback", attempt: 1, ms: 12725, costUsd: 0.00013 }from clearcote import Cloud, launch
browser = launch(cloud=True, challenge_service={"categories": ["token", "image"], "sites": ["shop.example"], "max_spend_eur": 0.2})
page = browser.new_page()
page.goto("https://shop.example/signup")
session_id = browser.cloud_session["id"]
browser.close()
for e in Cloud().browsers.events(session_id)["events"]:
if e["type"].startswith("challenge."):
print(e["type"], e["data"])