Pular para o conteúdo

Visualização ao vivo e sessões

Assista a um navegador hospedado ao vivo, assuma o controle ou compartilhe a visualização, gerencie as suas sessões e mantenha um navegador rodando para se reconectar a ele depois.

Visualização ao vivo: assistir, assumir o controle, compartilhar

No painel, clique numa sessão para ver para quais sites foi o tráfego dela e para assistir ao vivo. Clique em Take control para clicar, digitar, rolar, colar e navegar nela você mesmo, por exemplo para fazer login ou passar por uma verificação que o seu script não consegue. O seu script continua conectado o tempo todo, então pause-o enquanto você age. Input humano conta como atividade, então uma sessão que você está controlando não é fechada por inatividade. Share gera um link que qualquer pessoa pode abrir sem conta, só para assistir ou com controle, por 15 minutos a 4 horas e nunca além do fim da sessão.

Pela API:

bash
# a live-view WebSocket for a running session (open it within 60 s)
# binary messages are JPEG frames, text messages are {"url","title","tabs"}
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/live

# with control: the answer says "interactive": true when it was granted
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/live?control=1"

# a share link: control optional, 1 to 240 minutes (default 30)
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"control": false, "minutes": 60}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share

Com controle, envie mensagens de texto JSON pelo mesmo WebSocket. As coordenadas são frações (de 0 a 1) do frame que você está vendo; qualquer outra coisa é ignorada.

MensagemO que faz
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Pressiona (down), solta (up) ou move; n é o número de cliques e m, os modificadores (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Rola uma quantidade de pixels num ponto.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Uma tecla sendo pressionada ou solta, do jeito que um teclado envia.
{"t":"text","text":"pasted text"}Insere texto como se tivesse sido digitado (até 5000 caracteres).
{"t":"nav","a":"back"}, forward, reload ou {"t":"nav","a":"go","url":"example.com"}Histórico, recarregar ou abrir um endereço http(s).

GET /api/v1/browsers/<id> inclui traffic: os 20 sites com mais bytes naquela sessão.

Gerenciando sessões

bash
# one session: status, traffic, seconds, cost so far
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# stop it (a running browser closes within about 15 seconds)
curl -X DELETE -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# balance + your 20 most recent sessions
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers

# filtered by status and note text, up to 100; page back with before=<a createdAt you got>
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers?status=active,ended&note=shop-de&limit=50"

# label a session (null clears it)
curl -X PATCH -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"note": "shop-de nightly"}' https://www.clearcotelabs.com/api/v1/browsers/<id>

Dê uma note à sessão ao criá-la para encontrá-la de novo na lista e no painel. Para iniciar uma sessão no mesmo servidor de uma anterior (caches aquecidos, a mesma máquina), passe o worker daquela sessão; quando esse servidor estiver cheio, você recebe um 503, e não outro servidor.

Uma sessão também termina quando você fecha o navegador ou desconecta, e quando um dos limites abaixo é atingido. Um pedido de parada encerra na hora uma sessão à qual ninguém se conectou; um navegador em execução é fechado pelo servidor dele dentro de um intervalo de relatório, cerca de 15 segundos. O GET responde com:

json
{
  "id": "bs_…",
  "status": "active",                 // see the table below
  "proxy": "managed",                 // or "custom"
  "createdAt": "…", "startedAt": "…", "endedAt": null,
  "endReason": null,                  // set once ended, e.g. "user", "balance", "launch_failed"
  "stopRequested": false,
  "usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
  "traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
  "costEur": 0.0050,
  "pricing": { "eurPerGb": 1, "eurPerHour": 0 }
}
statusSignificado
pendingCreated; nobody has connected yet. Counts towards the concurrency limit until it starts or expires.
activeA browser is running and reporting usage.
lostNo usage report for 5 minutes. Billed up to the last report; a late report puts it back to active.
endedClosed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which.
expiredNobody connected within two minutes of creating it. Never billed.

A chamada de listagem, GET /api/v1/browsers, retorna { balanceEur, sessions: [...] } com os mesmos objetos de sessão, dos mais recentes para os mais antigos.

Mantendo o navegador aberto e reconectando

Por padrão, uma sessão termina quando o seu cliente desconecta. Inicie-a com keepAlive: true e o navegador continua rodando, com as abas, os cookies e o IP de saída, para que um script posterior (ou o mesmo, depois de um crash ou de fechar o notebook) continue de onde o anterior parou:

bash
# a new single-use connect URL for a running keepAlive session (connect within two minutes)
curl -X POST -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/connect
  • Deixe-o rodando desconectando: browser.close() do Playwright (via connectOverCDP ele só desconecta), browser.disconnect() do Puppeteer ou simplesmente encerrando o seu processo.
  • Encerre-o com DELETE /api/v1/browsers/<id> ou enviando o comando CDP Browser.close: o browser.close() do Puppeteer faz isso e, no Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). Até lá, ele continua ocupando uma vaga no seu limite de concorrência.
  • Um cliente por vez: uma reconexão enquanto outro cliente está conectado é recusada com 409, assim como uma reconexão a uma sessão iniciada sem keepAlive.
  • Os limites continuam valendo enquanto ninguém está conectado: idleTimeoutSec (aumente, até 1800, para um navegador ao qual você pretende voltar), timeoutSec, maxGb e o seu saldo. Uma página deixada aberta continua carregando tráfego em segundo plano, que é cobrado como qualquer outro.