Zum Inhalt springen

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.

FeldTypBedeutung
identitystringOne label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online.
fingerprintstringDevice 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.
lightStealthbooleanDefault true: varies only the metadata axes the host can back up. Set false to turn it off.
platformwindowsAlways 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.
brandChrome | Edge | Opera | VivaldiBrowser brand the persona presents.
timezoneIANA namee.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.
localestringAccept-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.
geoipbooleanOlder 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).
country2-letter codeManaged pool: exit country, e.g. us, de, gb.
stateregion codeManaged pool: exit state/region, e.g. ca, ny. Needs country.
citycity nameManaged pool: exit city, e.g. "los angeles". Needs state.
proxySessionstringManaged pool: sticky label. The same label returns the same exit IP later (kept for 24 hours).
timeoutSecnumberHard limit on the session length, in seconds (10 up to the account maximum below).
idleTimeoutSecnumberEnd the session after this long without a CDP command (10–1800).
maxGbnumberStop the session after this much traffic (0.001–1000).
headlessbooleanDefault 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.
humanizebooleanDefault 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".
keepAlivebooleanDefault 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.
versionstringRun 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".
urlhttp(s) URLOpened in the first tab before you connect: you find it already loading.
adblockbooleanRefuse known ad and tracker hosts before they load, so they are never billed. Default false.
solveSlidersbooleanDefault true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges".
solveCheckboxesbooleanDefault true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges".
solvePressHoldbooleanDefault 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".
challengeServicetrue | { 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".
recordbooleanDefault false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days).
notestringYour label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list.
workerstringPlace 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.

Stealth-Defaults und Identitäten

Jede Session startet mit den Einstellungen von der Seite Empfohlene Einstellungen: eine Windows-Persona (die Browser laufen auf Windows-Maschinen, also ist das das System, das sie belegen können), lightStealth an, ein Seed, Zeitzone und Sprache passend zur Exit-IP (mit Ihrem eigenen Proxy wie mit unserem), das Widevine-Modul, das ein Google Chrome mitbringt (damit requestMediaKeySystemAccess("com.widevine.alpha") gelingt), und menschliche Mausbewegungen (siehe unten). 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 rendert die Maschine, auf der die Session läuft. Die Grafikkarte, die eine Session an WebGL meldet, wird für jede Session aus einer Auswahl echter Modelle derselben Klasse wie die der Maschine gezogen, und dieselbe identity meldet dieselbe Karte. So melden Sessions auf einer Maschine unterschiedliche Karten, während die WebGL-Limits und die Antworten zu Video-Codecs zu ihnen passen. 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.

Menschenähnliche Eingaben

Playwright und Puppeteer bewegen die Maus von Haus aus in einem Sprung: Eine einzige Bewegung landet auf dem Ziel, und der Klick folgt ein bis zwei Millisekunden später. Ein gehosteter Browser glättet das auf dem Server, direkt neben dem Browser, für jeden Client: Landet eine Bewegung oder ein Klick weit entfernt von der aktuellen Cursorposition, führt der Server den Cursor zuerst so dorthin, wie es eine Hand tun würde (in einer Kurve, mit dem Tempo und den kleinen Korrekturen einer echten Handbewegung), und liefert dann Ihr Event aus. Gedrückt wird erst einen Moment nach der Ankunft des Cursors, so wie eine Hand zur Ruhe kommt, und jeder Klick wird so lange gehalten, wie ein Mensch drückt, bevor er losgelassen wird. Eine Identität behält eine Art, sich zu bewegen. Ihr Skript braucht keine Änderung und wird pro Klick um etwa eine Sekunde langsamer.

Beim Scrollen geschieht dasselbe. Ein Scrollen um mehr als eine Mausrad-Raste (100 px auf den Windows- Rechnern, auf denen die Browser laufen) kommt in ganzen Rasten und kurzen Schüben an, so wie ein Finger ein Mausrad dreht, nachdem der Cursor zur Scrollstelle gewandert ist, falls er woanders war. Die Seite scrollt genau die angeforderte Strecke, die letzte Raste trägt den Rest, und Ihr Aufruf kehrt zurück, sobald diese Raste gesendet ist.

Unverändert so, wie Sie sie senden, bleiben: Bewegungen um wenige Pixel (ein Client, der sich schon in kleinen Schritten bewegt, wie das eigene humanize des SDK), Ziehbewegungen mit gedrückter Maustaste, ein Scrollen um höchstens eine Raste, Touch und die Tastatur. Übergeben Sie humanize: false, wenn Sie die rohe Geschwindigkeit brauchen.

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.

javascript
// 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 ("156.0.8078.47-r51"), nur den Rebuild ("r51"), eine Chromium-Version oder Major-Version ("155" 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.

javascript
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 ... " ]
  • 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.