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.

Furtivité par défaut et identités

Chaque session part des réglages décrits sur la page Réglages recommandés : lightStealth activé, un seed, et un fuseau horaire et une langue qui suivent l’IP de sortie. Avec lightStealth (le défaut), le 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 ceux de la machine sur laquelle tourne la session. 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é du 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 un 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 son propre seed et sa propre IP. À elle seule, une identité ne conserve pas les cookies : pour cela, utilisez un profil.

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ême identity ou fingerprint pour 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: true reçoit 409 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 avec DELETE /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 ("152.0.7977.82-r21"), seulement le rebuild ("r21"), une version ou une version majeure de Chromium ("152" 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: "152.0.7977.82-r21" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "152.0.7977.82", revision: "r21", pinned: true }
// warnings -> [ "This session runs 152.0.7977.82-r21, 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 engine de la réponse indique toujours quelle version exécute la session, épinglée ou non.
• Une version qui n’existe pas renvoie une erreur 400 avec le code UNKNOWN_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

• url ouvre une page dans le premier onglet avant votre connexion : elle est déjà en cours de chargement quand votre script s’y attache.
• adblock: true refuse 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.