Options et identités
Ce que vous pouvez définir au démarrage d'un navigateur hébergé : les options, la furtivité par défaut et les identités, les profils qui vous gardent connecté, une version épinglée et la page de démarrage.
Options
Toutes sont facultatives. Envoyez-les dans le corps JSON de l’appel de création.
| Champ | Type | Signification |
|---|---|---|
identity | string | One label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online. |
fingerprint | string | Device seed only (no IP pinning). The same seed gives the same device profile every time; with lightStealth on it picks from a small set of metadata profiles. |
lightStealth | boolean | Default true: varies only the metadata axes the host can back up. Set false to turn it off. |
platform | windows | Always windows: the browsers run on Windows machines, and a persona of another system there reports GPU limits and fonts no such machine has. Another value starts a Windows session and warnings says so. |
brand | Chrome | Edge | Opera | Vivaldi | Browser brand the persona presents. |
timezone | IANA name | e.g. America/New_York. Omitted = the exit IP's. Given, it is kept as you wrote it and checked against the exit IP: under geoIdentity "strict" (the default) a time zone the exit's country does not use refuses the launch. |
locale | string | Accept-Language, e.g. en-US,en. Omitted = a language of the exit IP's country. Given, it is kept and checked against the exit like timezone. |
geoIdentity | "strict" | "warn" | "auto" | "manual" | "off" | { mode?, acknowledge?, localePolicy? } | Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event. |
geoip | boolean | Older option, read only when geoIdentity is not set: true = geoIdentity "auto", false = "manual". |
proxy | "managed" | { server, username?, password? } | Omitted = managed residential pool. Or your own proxy: http://, socks5:// or socks5h:// (rules below). |
country | 2-letter code | Managed pool: exit country, e.g. us, de, gb. |
state | region code | Managed pool: exit state/region, e.g. ca, ny. Needs country. |
city | city name | Managed pool: exit city, e.g. "los angeles". Needs state. |
proxySession | string | Managed pool: sticky label. The same label returns the same exit IP later (kept for 24 hours). |
timeoutSec | number | Hard limit on the session length, in seconds (10 up to the account maximum below). |
idleTimeoutSec | number | End the session after this long without a CDP command (10–1800). |
maxGb | number | Stop the session after this much traffic (0.001–1000). |
headless | boolean | Default true. With false the browser opens a real window on the server. Under the default lightStealth, the page then reports that server's own display (its whole screen, with the window maximized) instead of your identity's screen size; the identity still sets CPU cores, memory, colour depth and pixel ratio. Keep the default when the identity's screen should apply. |
humanize | boolean | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input". |
keepAlive | boolean | Default false. Keep the browser running when your client disconnects, until you end it (DELETE, or the CDP command Browser.close) or a limit does; reconnect with POST /api/v1/browsers/<id>/connect. |
version | string | Run a specific Clearcote release, e.g. "152.0.7977.82-r21" or "r21". Omitted = the current release. See "Pinning a release". |
profile | "name" | { name, persist? } | Load a saved profile (cookies + site storage). With persist: true, save it back when the session ends. See "Profiles". |
url | http(s) URL | Opened in the first tab before you connect: you find it already loading. |
adblock | boolean | Refuse known ad and tracker hosts before they load, so they are never billed. Default false. |
solveSliders | boolean | Default true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges". |
solveCheckboxes | boolean | Default true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges". |
solvePressHold | boolean | Default true. "Press and hold" verification buttons are held for you until they report done, in any tab or frame; false leaves them to your script. See "Press-and-hold challenges". |
challengeService | true | { categories?, sites?, key?, apiKey?, mode?, maxSolves?, maxSpendEur? } | Default off. Challenges the free actions cannot clear go to a solving service, with your own key or ours (billed per solve). true (or no categories) auto-selects: every challenge it recognises, in token, clearance, block-page and image; or list categories and sites yourself. See "Challenge service". |
record | boolean | Default false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days). |
note | string | Your label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list. |
worker | string | Place the session on the same server as an earlier one (its worker). If that server is full or offline, it starts on another one and warnings says so. |
Furtivité par défaut et identités
Chaque session part des réglages décrits sur la page Réglages recommandés : une persona Windows (les navigateurs tournent sur des machines Windows, c’est donc le système qu’ils peuvent étayer), lightStealth activé, une seed, un fuseau horaire et une langue qui suivent l’IP de sortie, avec votre propre proxy comme avec le nôtre, le module Widevine dont dispose un Google Chrome (pour que requestMediaKeySystemAccess("com.widevine.alpha") aboutisse), et des mouvements de souris humains (voir plus bas). Avec lightStealth (le défaut), la seed choisit le profil d’appareil dans un petit ensemble qui fait varier le nombre de cœurs CPU, la mémoire et la densité de pixels ; canvas, WebGL et audio sont rendus par la machine sur laquelle tourne la session. La carte graphique qu’une session annonce à WebGL est tirée, pour chaque session, d’un éventail de modèles réels de la même classe que celle de cette machine, et une même identity annonce la même carte ; les sessions d’une même machine annoncent donc des cartes différentes, tandis que les limites WebGL et les réponses sur les codecs vidéo restent cohérentes avec elles. Passez lightStealth: false pour une persona complète propre à chaque seed : les pixels relus depuis canvas et WebGL reçoivent un bruit par site dérivé de la seed, et les chaînes GPU, l’écran et les réglages audio (fréquence d’échantillonnage, latence) suivent la persona. Sans identity ni fingerprint, chaque session reçoit une seed aléatoire et une nouvelle IP.
Passez identity: "account-42" pour retrouver le même profil d’appareil lors des sessions suivantes, sur la même IP tant que cette IP résidentielle reste en ligne : c’est ce qu’attend un compte connecté. Les identités sont propres à votre compte : un autre client qui utilise le même libellé obtient sa propre seed et sa propre IP. À elle seule, une identité ne conserve pas les cookies : pour cela, utilisez un profil.
Entrées humanisées
Playwright et Puppeteer d’origine déplacent la souris d’un seul bond : un unique mouvement atterrit sur la cible et le clic suit une ou deux millisecondes plus tard. Un navigateur hébergé lisse cela côté serveur, juste à côté du navigateur, quel que soit le client : quand un mouvement ou un clic tombe loin de la position du curseur, le serveur y amène d’abord le curseur comme le ferait une main (en courbe, avec la vitesse et les petites corrections d’un vrai geste), puis transmet votre événement. L’appui vient un instant après l’arrivée du curseur, comme une main qui se pose, et chaque clic est maintenu pendant une durée d’appui humaine avant d’être relâché. Une identité garde une seule façon de bouger. Votre script ne demande aucune modification, et il ralentit d’environ une seconde par clic.
Le défilement reçoit le même traitement. Un défilement de plus d’un cran de molette (100 px sur les machines Windows où tournent les navigateurs) arrive en crans entiers, par courtes rafales, comme un doigt qui fait tourner une molette, après que le curseur s’est déplacé jusqu’au point de défilement s’il était ailleurs. La page défile exactement de la distance demandée, le dernier cran portant le reste, et votre appel revient quand ce cran est parti.
Restent exactement tels que vous les envoyez : les mouvements de quelques pixels (un client qui se déplace déjà par petits pas, comme le humanize du SDK lui-même), les glissements avec un bouton enfoncé, un défilement d’un cran ou moins, le tactile et le clavier. Passez humanize: false quand vous avez besoin de la vitesse brute.
Profils : se connecter une seule fois
Un profil conserve sous un nom les cookies, le localStorage et l’IndexedDB d’une session, si bien que la session suivante sous ce nom démarre déjà connectée. Passez profile: { name: "shop-account", persist: true } pour le charger puis le réenregistrer à la fin de la session, ou simplement profile: "shop-account" pour le charger en lecture seule. La première session sous un nouveau nom démarre vide et crée le profil.
// Every run: the same body. The first one starts signed out; sign in, then close the browser
// and the session saves the cookies and site storage. Every later run starts signed in.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
method: "POST",
headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
body: JSON.stringify({ profile: { name: "shop-account", persist: true }, country: "de" }),
});- Même appareil, même IP. Un profil apporte sa propre identité (
profile:<name>) : le site voit la même empreinte, et la même IP résidentielle tant que celle-ci reste en ligne, comme pour un client qui revient. Passez vous-mêmeidentityoufingerprintpour en décider autrement, et gardez le même pays d’une exécution à l’autre. - Une seule session en écriture à la fois. Seule une session en cours peut enregistrer dans un profil ; une deuxième avec
persist: truereçoit409 PROFILE_IN_USE. Des sessions en lecture seule peuvent tourner en parallèle et voient le dernier état enregistré. - Enregistré à la fin de la session, que vous fermiez le navigateur, que vous vous déconnectiez, que vous l’arrêtiez ou qu’une limite y mette fin. Si le navigateur a planté, l’état enregistré précédent est conservé plutôt que remplacé par un état partiel. Les cookies de session (ceux sans date d’expiration) sont supprimés, comme un vrai navigateur les supprime au redémarrage.
- Jusqu’à environ 3,5 Mo une fois compressé. Si l’IndexedDB d’un site fait dépasser cette taille, l’IndexedDB est laissé de côté ; les cookies et le localStorage sont tout de même enregistrés.
- Privé. Un profil n’appartient qu’à vous (le « shop-account » d’un autre client est un autre profil), il est stocké chiffré et n’est transmis qu’au serveur qui exécute votre session. Listez vos profils avec
GET /api/v1/browsers/profiles, supprimez-en un avecDELETE /api/v1/browsers/profiles/<name>, ou passez par le tableau de bord.
Déjà connecté ailleurs ? La synchronisation des cookies copie ces cookies dans un profil, pour que la première session démarre elle aussi connectée.
Épingler une version
Les sessions exécutent la version actuelle de Clearcote. Pour en exécuter une plus ancienne, passez version : la version complète ("156.0.8078.47-r51"), seulement le rebuild ("r51"), une version ou une version majeure de Chromium ("155" prend le build le plus récent de celle-ci), ou "latest". Ce sont les mêmes versions que télécharge l’option version du SDK : une session hébergée et une exécution locale épinglées sur la même valeur utilisent donc le même build.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
method: "POST",
headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
body: JSON.stringify({ identity: "account-1", version: "156.0.8078.47-r51" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine -> { version: "156.0.8078.47", revision: "r51", pinned: true }
// warnings -> [ "This session runs 156.0.8078.47-r51, older than the current ... " ]- Vérifiez
warnings. Une version plus ancienne n’a pas ce que les versions suivantes ont ajouté. Les options et les correctifs arrivés après elle peuvent manquer, ou être ignorés silencieusement au lieu d’être rejetés : un réglage qui fonctionne sur la version actuelle peut donc ne rien faire, sans rien signaler, sur une version épinglée. - Le champ
enginede la réponse indique toujours quelle version exécute la session, épinglée ou non. - Une version qui n’existe pas renvoie une erreur
400avec le codeUNKNOWN_VERSION, et le message liste les versions parmi lesquelles vous pouvez choisir. - La première session sur une version que nos serveurs n’ont pas encore utilisée peut mettre jusqu’à une minute de plus à démarrer, le temps de récupérer le build. Les sessions suivantes sur cette version démarrent aussi vite que les autres.
Page de démarrage et blocage des publicités
urlouvre une page dans le premier onglet avant votre connexion : elle est déjà en cours de chargement quand votre script s’y attache.adblock: truerefuse les requêtes vers les hôtes connus de publicité, de vérification publicitaire et d’analytics avant même qu’elles ne partent : elles ne sont donc jamais facturées. La liste est volontairement prudente (tag managers, outils de consentement, SDK de connexion et CAPTCHA ne sont pas touchés), mais quelques sites remarquent l’absence de publicités ; laissez l’option désactivée là où cela compte.