Saltar al contenido

Vista en vivo y sesiones

Observa un navegador alojado en vivo, toma el control o comparte la vista, administra tus sesiones y mantén un navegador en ejecución para reconectarte a él más tarde.

Vista en vivo: observar, tomar el control, compartir

En el panel, haz clic en una sesión para ver a qué sitios fue su tráfico y para verla en vivo. Pulsa “Take control” para hacer clic, escribir, desplazarte, pegar y navegar tú mismo, por ejemplo para iniciar sesión o superar una verificación que tu script no puede. Tu script sigue conectado todo el tiempo, así que ponlo en pausa mientras actúas. La interacción humana cuenta como actividad, así que una sesión que estás controlando no se cierra por inactividad. “Share” genera un enlace que cualquiera puede abrir sin cuenta, solo para ver o con control, válido de 15 minutos a 4 horas y nunca más allá del final de la sesión.

A través de la 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

Con control, envía mensajes de texto JSON por el mismo WebSocket. Las coordenadas son fracciones (de 0 a 1) del fotograma que estás viendo; todo lo demás se ignora.

MensajeQué hace
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Pulsar (down), soltar (up) o mover (move); n es la cantidad de clics y m, los modificadores (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Desplazarse una cantidad de píxeles en un punto.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Una tecla que se presiona o se suelta, tal como la envía un teclado.
{"t":"text","text":"pasted text"}Insertar texto como si se escribiera (hasta 5000 caracteres).
{"t":"nav","a":"back"}, forward, reload o {"t":"nav","a":"go","url":"example.com"}Historial, recargar o abrir una dirección http(s).

GET /api/v1/browsers/<id> incluye traffic: los 20 sitios principales por bytes de esa sesión.

Administrar sesiones

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>

Ponle una note a la sesión al crearla para encontrarla después en la lista y en el panel. Para iniciar una sesión en el mismo servidor que una anterior (cachés ya calientes, la misma máquina), pasa el worker de esa sesión; si ese servidor está lleno, recibes un 503, no otro servidor.

Una sesión también termina cuando cierras el navegador o te desconectas, y cuando se alcanza alguno de los límites que se describen más abajo. Una solicitud de detención termina de inmediato una sesión a la que nadie se conectó; un navegador en ejecución lo cierra su servidor dentro de un intervalo de reporte, unos 15 segundos. GET responde con:

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.

La llamada de listado, GET /api/v1/browsers, devuelve { balanceEur, sessions: [...] } con los mismos objetos de sesión, de la más reciente a la más antigua.

Mantener un navegador abierto y reconectarse

Por defecto, una sesión termina cuando tu cliente se desconecta. Iníciala con keepAlive: true y el navegador sigue en ejecución, con sus pestañas, cookies e IP de salida, para que un script posterior (o el mismo, después de un fallo o de cerrar la laptop) retome donde se quedó el anterior:

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
  • Para dejarlo en ejecución, desconéctate: con browser.close() de Playwright (sobre connectOverCDP solo desconecta), con browser.disconnect() de Puppeteer o simplemente terminando tu proceso.
  • Para terminarlo, usa DELETE /api/v1/browsers/<id> o envía el comando CDP Browser.close: el browser.close() de Puppeteer lo hace, y en Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). Hasta entonces, sigue ocupando su lugar en tu límite de concurrencia.
  • Un cliente a la vez: una reconexión mientras hay otro cliente conectado se rechaza con 409, igual que una para una sesión iniciada sin keepAlive.
  • Los límites siguen aplicándose mientras nadie está conectado: idleTimeoutSec (súbelo, hasta 1800, si piensas volver a ese navegador), timeoutSec, maxGb y tu saldo. Una página que queda abierta sigue cargando su tráfico en segundo plano, que se factura como cualquier otro.