Aller au contenu

Vue en direct et sessions

Suivez un navigateur hébergé en direct, prenez la main ou partagez la vue, gérez vos sessions et gardez un navigateur ouvert pour vous y reconnecter plus tard.

Vue en direct : regarder, prendre la main, partager

Dans le tableau de bord, cliquez sur une session pour voir vers quels sites est allé son trafic et pour la suivre en direct. Appuyez sur « Take control » pour cliquer, saisir du texte, faire défiler, coller et naviguer vous-même, par exemple pour vous connecter ou franchir une vérification que votre script ne sait pas franchir. Votre script reste connecté pendant tout ce temps : mettez-le en pause pendant que vous intervenez. Les saisies humaines comptent comme de l’activité : une session que vous pilotez n’est donc pas fermée pour inactivité. « Share » crée un lien que n’importe qui peut ouvrir sans compte, en lecture seule ou avec le contrôle, pour une durée de 15 minutes à 4 heures et jamais au-delà de la fin de la session.

Via l’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

Avec le contrôle, envoyez des messages texte JSON sur le même WebSocket. Les coordonnées sont des fractions (de 0 à 1) de l’image que vous regardez ; tout le reste est ignoré.

MessageEffet
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}Appui (down), relâchement (up) ou move ; n est le nombre de clics, m les modificateurs (Alt 1, Ctrl 2, Meta 4, Shift 8).
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}Défilement d’un nombre de pixels à un point donné.
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}Une touche enfoncée ou relâchée, telle qu’un clavier l’envoie.
{"t":"text","text":"pasted text"}Insère du texte comme s’il avait été tapé (jusqu’à 5000 caractères).
{"t":"nav","a":"back"}, forward, reload ou {"t":"nav","a":"go","url":"example.com"}Historique, rechargement ou ouverture d’une adresse http(s).

GET /api/v1/browsers/<id> inclut traffic : les 20 sites qui ont consommé le plus d’octets pendant cette session.

Gérer les sessions

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>

Donnez une note à une session dès sa création pour la retrouver dans la liste et dans le tableau de bord. Pour démarrer une session sur le même serveur qu’une session précédente (caches déjà chauds, même machine), passez le worker de cette session ; si ce serveur est plein, vous recevez une 503, pas un autre serveur.

Une session se termine aussi quand vous fermez le navigateur ou vous déconnectez, et quand l’une des limites ci-dessous est atteinte. Une demande d’arrêt met fin immédiatement à une session à laquelle personne ne s’est connecté ; un navigateur en cours d’exécution est fermé par son serveur dans l’intervalle de remontée suivant, soit environ 15 secondes. GET répond avec :

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

L’appel de liste, GET /api/v1/browsers, renvoie { balanceEur, sessions: [...] } avec les mêmes objets de session, du plus récent au plus ancien.

Garder un navigateur ouvert et s’y reconnecter

Par défaut, une session se termine quand votre client se déconnecte. Démarrez-la avec keepAlive: true et le navigateur continue au contraire de tourner, avec ses onglets, ses cookies et son IP de sortie : un script ultérieur (ou le même, après un plantage ou un portable refermé) peut reprendre là où le précédent s’était arrêté :

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
  • Laissez-le tourner en vous déconnectant : browser.close() de Playwright (via connectOverCDP, il ne fait que se déconnecter), browser.disconnect() de Puppeteer, ou tout simplement la fin de votre processus.
  • Arrêtez-le avec DELETE /api/v1/browsers/<id>, ou en envoyant la commande CDP Browser.close : c’est ce que fait browser.close() de Puppeteer, et dans Playwright, await (await browser.newBrowserCDPSession()).send("Browser.close"). D’ici là, il occupe toujours une place dans votre limite de concurrence.
  • Un seul client à la fois : une reconnexion alors qu’un autre client est attaché est refusée avec 409, tout comme une reconnexion à une session démarrée sans keepAlive.
  • Les limites s’appliquent même quand personne n’est connecté : idleTimeoutSec (augmentez-le, jusqu’à 1800, pour un navigateur auquel vous comptez revenir), timeoutSec, maxGb et votre solde. Une page laissée ouverte continue de générer son trafic en arrière-plan, facturé comme n’importe quel autre.