Zum Inhalt springen

Live-Ansicht und Sessions

Sehen Sie einem gehosteten Browser live zu, übernehmen Sie die Steuerung oder teilen Sie die Ansicht, verwalten Sie Ihre Sessions und lassen Sie einen Browser weiterlaufen, damit Sie sich später wieder mit ihm verbinden können.

Live-Ansicht: zusehen, übernehmen, teilen

Klicken Sie im Dashboard auf eine Session, um zu sehen, an welche Sites ihr Traffic ging, und um sie live zu verfolgen. Über Take control können Sie selbst darin klicken, tippen, scrollen, einfügen und navigieren, etwa um sich anzumelden oder eine Prüfung zu bestehen, an der Ihr Skript scheitert. Ihr Skript bleibt die ganze Zeit verbunden; pausieren Sie es also, während Sie eingreifen. Menschliche Eingaben zählen als Aktivität, daher wird eine Session, die Sie gerade steuern, nicht wegen Inaktivität geschlossen. Share erzeugt einen Link, den jeder ohne Account öffnen kann, nur zum Zusehen oder mit Steuerung, für 15 Minuten bis 4 Stunden und nie über das Ende der Session hinaus.

Über die 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

Mit Steuerung senden Sie JSON-Textnachrichten über denselben WebSocket. Koordinaten sind Anteile (0 bis 1) des Frames, den Sie gerade sehen; alles andere wird ignoriert.

NachrichtWirkung
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Drücken (down), Loslassen (up) oder move; n ist die Anzahl der Klicks, m sind die Modifier-Tasten (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}An einer Position um eine Anzahl Pixel scrollen.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Eine Taste wird gedrückt oder losgelassen, so wie eine Tastatur es sendet.
{"t":"text","text":"pasted text"}Text einfügen, als wäre er getippt (bis zu 5000 Zeichen).
{"t":"nav","a":"back"}, forward, reload oder {"t":"nav","a":"go","url":"example.com"}Verlauf, Neuladen oder eine http(s)-Adresse öffnen.

GET /api/v1/browsers/<id> enthält traffic: die 20 Sites mit den meisten Bytes in dieser Session.

Sessions verwalten

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>

Geben Sie einer Session beim Anlegen eine note mit, um sie in der Liste und im Dashboard wiederzufinden. Um eine Session auf demselben Server wie eine frühere zu starten (warme Caches, dieselbe Maschine), übergeben Sie den worker jener Session; ist dieser Server voll, erhalten Sie einen 503 und keinen anderen Server.

Eine Session endet außerdem, wenn Sie den Browser schließen oder die Verbindung trennen, und wenn eines der unten genannten Limits erreicht ist. Eine Stop-Anfrage beendet eine Session, mit der sich niemand verbunden hat, sofort; einen laufenden Browser schließt sein Server innerhalb eines Meldeintervalls, also nach etwa 15 Sekunden. GET antwortet mit:

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 }
}
statusBedeutung
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.

Der Listenaufruf GET /api/v1/browsers liefert { balanceEur, sessions: [...] } mit denselben Session-Objekten, die neuesten zuerst.

Browser offen halten und neu verbinden

Standardmäßig endet eine Session, sobald Ihr Client die Verbindung trennt. Starten Sie sie mit keepAlive: true, läuft der Browser stattdessen weiter, mit seinen Tabs, Cookies und seiner Exit-IP. So kann ein späteres Skript (oder dasselbe nach einem Absturz oder einem zugeklappten Laptop) dort weitermachen, wo das letzte aufgehört hat:

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
  • Sie lassen ihn weiterlaufen, indem Sie die Verbindung trennen: mit browser.close() in Playwright (über connectOverCDP trennt das nur die Verbindung), mit browser.disconnect() in Puppeteer oder indem Sie einfach Ihren Prozess beenden.
  • Sie beenden ihn mit DELETE /api/v1/browsers/<id> oder indem Sie den CDP-Befehl Browser.close senden: Das tut browser.close() in Puppeteer, in Playwright geht es mit await (await browser.newBrowserCDPSession()).send("Browser.close"). Bis dahin belegt er einen Platz in Ihrem Concurrency-Limit.
  • Immer nur ein Client: Ein Reconnect, während ein anderer Client verbunden ist, wird mit 409 abgelehnt, ebenso einer für eine Session, die ohne keepAlive gestartet wurde.
  • Die Limits gelten auch, während niemand verbunden ist: idleTimeoutSec (für einen Browser, zu dem Sie zurückkehren wollen, auf bis zu 1800 erhöhen), timeoutSec, maxGb und Ihr Guthaben. Eine offen gelassene Seite lädt weiter ihren Hintergrund-Traffic, der wie jeder andere berechnet wird.