Optionen und Identitäten

Was Sie beim Start eines gehosteten Browsers festlegen können: die Optionen, die Stealth-Defaults und Identitäten, Profile, die Sie angemeldet halten, ein gepinntes Release und die Startseite.

Optionen

Alle optional. Senden Sie sie als JSON-Body des Create-Aufrufs.

Stealth-Defaults und Identitäten

Jede Session startet mit den Einstellungen von der Seite Empfohlene Einstellungen: lightStealth an, ein Seed sowie Zeitzone und Sprache passend zur Exit-IP. Mit lightStealth (dem Standard) wählt der Seed das Geräteprofil aus einer kleinen Auswahl, die CPU-Kerne, Arbeitsspeicher und Pixel-Ratio variiert; Canvas, WebGL und Audio sind die der Maschine, auf der die Session läuft. Setzen Sie lightStealth: false für eine vollständige Persona pro Seed: Canvas- und WebGL-Readbacks bekommen aus dem Seed ein Rauschen pro Site, und GPU-Strings, Bildschirm und Audio-Einstellungen (Sample-Rate, Latenz) folgen der Persona. Ohne identity oder fingerprint erhält jede Session einen zufälligen Seed und eine neue IP.

Mit identity: "account-42" kommen Sie in späteren Sessions mit demselben Geräteprofil zurück, und zwar auf derselben IP, solange diese Residential-IP online bleibt – genau das erwartet ein eingeloggter Account. Identitäten gelten nur innerhalb Ihres Accounts: Ein anderer Kunde mit demselben Label erhält seinen eigenen Seed und seine eigene IP. Eine Identität allein speichert keine Cookies; dafür verwenden Sie ein Profil.

Profile: einmal anmelden

Ein Profil speichert Cookies, localStorage und IndexedDB einer Session unter einem Namen, sodass die nächste Session mit diesem Namen bereits angemeldet startet. Übergeben Sie profile: { name: "shop-account", persist: true }, um es zu laden und beim Ende der Session zurückzuspeichern, oder nur profile: "shop-account", um es schreibgeschützt zu laden. Die erste Session mit einem neuen Namen startet leer und legt das Profil an.

// 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" }),
});

• Gleiches Gerät, gleiche IP. Ein Profil bringt seine eigene Identität mit (profile:<name>), sodass die Site denselben Fingerprint sieht und, solange diese IP online bleibt, dieselbe Residential-IP – wie bei einem wiederkehrenden Kunden. Übergeben Sie selbst identity oder fingerprint, wenn Sie etwas anderes wollen, und behalten Sie zwischen den Läufen dasselbe Land bei.
• Immer nur ein Schreiber. Nur eine laufende Session darf in ein Profil speichern; eine zweite mit persist: true erhält 409 PROFILE_IN_USE. Schreibgeschützte Sessions können parallel laufen und sehen den zuletzt gespeicherten Stand.
• Gespeichert wird beim Ende der Session, egal ob Sie den Browser schließen, die Verbindung trennen, ihn stoppen oder ein Limit die Session beendet. Ist der Browser abgestürzt, bleibt der zuvor gespeicherte Stand erhalten, statt durch einen unvollständigen ersetzt zu werden. Session-Cookies (ohne Ablaufdatum) werden verworfen, so wie ein echter Browser sie beim Neustart verwirft.
• Bis etwa 3,5 MB komprimiert. Wird es durch die IndexedDB einer Site größer, bleibt die IndexedDB außen vor; Cookies und localStorage werden trotzdem gespeichert.
• Privat. Ein Profil gehört nur Ihnen („shop-account“ eines anderen Kunden ist ein anderes Profil), wird verschlüsselt gespeichert und nur an den Server übergeben, auf dem Ihre Session läuft. Auflisten mit GET /api/v1/browsers/profiles, löschen mit DELETE /api/v1/browsers/profiles/<name>, oder Sie nutzen das Dashboard.

Schon anderswo angemeldet? Cookie-Sync kopiert diese Cookies in ein Profil, sodass auch die erste Session angemeldet startet.

Release pinnen

Sessions laufen mit dem aktuellen Clearcote-Release. Für ein älteres übergeben Sie version: das vollständige Release ("152.0.7977.82-r21"), nur den Rebuild ("r21"), eine Chromium-Version oder Major-Version ("152" wählt deren neuesten Build) oder "latest". Es sind dieselben Releases, die die SDK-Option version herunterlädt – eine gehostete Session und ein lokaler Lauf mit demselben Pin verwenden also denselben 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 ... " ]

• Prüfen Sie warnings. Einem älteren Release fehlt, was spätere Releases hinzugefügt haben. Optionen und Fixes, die danach kamen, können fehlen oder stillschweigend ignoriert statt abgelehnt werden. Eine Einstellung, die auf dem aktuellen Release funktioniert, kann auf einem gepinnten also unbemerkt wirkungslos bleiben.
• engine in der Antwort nennt immer das Release, mit dem die Session läuft, ob gepinnt oder nicht.
• Ein Release, das es nicht gibt, ergibt einen 400 mit dem Code UNKNOWN_VERSION, und die Meldung listet die Releases auf, die Sie wählen können.
• Die erste Session auf einem Release, das unsere Server noch nicht verwendet haben, kann bis zu einer Minute länger zum Starten brauchen, während der Build geladen wird. Weitere Sessions darauf starten so schnell wie jede andere.

Startseite und Werbeblocker

• url öffnet eine Seite im ersten Tab, bevor Sie sich verbinden – sie lädt also schon, wenn sich Ihr Skript anhängt.
• adblock: true lehnt Requests an bekannte Werbe-, Ad-Verification- und Analytics-Hosts ab, bevor sie überhaupt gestellt werden, sodass sie nie berechnet werden. Die Liste ist bewusst konservativ (Tag-Manager, Consent-Tools, Login-SDKs und CAPTCHAs bleiben unangetastet), aber einige Sites bemerken fehlende Werbung; lassen Sie die Option dort aus, wo das eine Rolle spielt.