Saltar al contenido

Opciones e identidades

Lo que puedes configurar al iniciar un navegador alojado: las opciones, la configuración stealth predeterminada y las identidades, los perfiles que mantienen tu sesión iniciada, una versión fijada y la página de inicio.

Opciones

Todas son opcionales. Envíalas como cuerpo JSON de la llamada de creación.

CampoTipoSignificado
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.

Configuración stealth predeterminada e identidades

Cada sesión parte de los ajustes de la página de configuración recomendada: una persona Windows (los navegadores corren en máquinas Windows, así que ese es el sistema que pueden respaldar), lightStealth activado, un seed, zona horaria e idioma que siguen a la IP de salida con tu propio proxy o con el nuestro, el módulo Widevine que trae un Google Chrome (para que requestMediaKeySystemAccess("com.widevine.alpha") funcione) y movimiento humano del mouse (más abajo). Con lightStealth (el valor por defecto), el seed elige el perfil de dispositivo dentro de un conjunto pequeño que varía los núcleos de CPU, la memoria y el pixel ratio; canvas, WebGL y audio los renderiza la máquina donde corre la sesión. La tarjeta gráfica que una sesión reporta a WebGL se elige para cada sesión entre una gama de modelos reales de la misma clase que la de esa máquina, y la misma identity reporta la misma tarjeta, así que las sesiones en una misma máquina reportan tarjetas distintas mientras los límites de WebGL y las respuestas sobre códecs de video siguen siendo coherentes con ellas. Define lightStealth: false para tener una persona completa por seed: las lecturas de canvas y WebGL reciben ruido por sitio derivado del seed, y las cadenas de la GPU, la pantalla y la configuración de audio (frecuencia de muestreo, latencia) siguen a la persona. Sin identity ni fingerprint, cada sesión recibe un seed aleatorio y una IP nueva.

Pasa identity: "account-42" para volver en sesiones posteriores con el mismo perfil de dispositivo, y con la misma IP mientras esa IP residencial siga en línea, que es lo que espera una cuenta con la sesión iniciada. Las identidades son privadas de tu cuenta: otro cliente que use la misma etiqueta recibe su propio seed y su propia IP. Por sí sola, una identidad no conserva cookies: para eso, usa un perfil.

Entrada humanizada

Playwright y Puppeteer, tal como vienen, mueven el mouse de un salto: un único movimiento cae sobre el objetivo y el clic llega uno o dos milisegundos después. Un navegador alojado suaviza eso en el servidor, junto al navegador, para cualquier cliente: cuando un movimiento o un clic cae lejos de donde está el cursor, el servidor primero lleva el cursor hasta allí como lo haría una mano (en curva, con la velocidad y las pequeñas correcciones de un gesto real) y después entrega tu evento. La pulsación llega un momento después de que el cursor se detiene, como una mano que se asienta, y cada clic se mantiene presionado durante un tiempo de pulsación humano antes de soltarse. Una identidad conserva una sola forma de moverse. Tu script no necesita cambios, y se vuelve más lento en alrededor de un segundo por clic.

El desplazamiento recibe el mismo trato. Un desplazamiento de más de un paso de la rueda (100 px en las máquinas Windows donde corren los navegadores) llega en pasos completos, en ráfagas cortas, como un dedo que gira una rueda, después de que el cursor se haya movido al punto de desplazamiento si estaba en otro lugar. La página se desplaza exactamente la distancia que pediste, el último paso lleva el resto, y tu llamada vuelve cuando ese paso ya salió.

Quedan exactamente como los envías: los movimientos de pocos píxeles (un cliente que ya se mueve en pasos pequeños, como el propio humanize del SDK), los arrastres con un botón presionado, un desplazamiento de un paso de la rueda o menos, la entrada táctil y el teclado. Pasa humanize: false cuando necesites la velocidad original.

Perfiles: inicia sesión una sola vez

Un perfil guarda las cookies, el localStorage y el IndexedDB de una sesión bajo un nombre, así la siguiente sesión con ese nombre arranca ya autenticada. Pasa profile: { name: "shop-account", persist: true } para cargarlo y volver a guardarlo cuando termine la sesión, o simplemente profile: "shop-account" para cargarlo en modo de solo lectura. La primera sesión con un nombre nuevo empieza vacía y lo crea.

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" }),
});
  • Mismo dispositivo, misma IP. Un perfil trae su propia identidad (profile:<name>), así que el sitio ve la misma huella digital, y la misma IP residencial mientras esa IP siga en línea, como un cliente que regresa. Si prefieres otra cosa, pasa tú mismo identity o fingerprint, y mantén el mismo país entre ejecuciones.
  • Un solo escritor a la vez. Solo una sesión en ejecución puede guardar en un perfil; una segunda con persist: true recibe 409 PROFILE_IN_USE. Las sesiones de solo lectura pueden correr en paralelo y ven el último estado guardado.
  • Se guarda cuando termina la sesión, ya sea que cierres el navegador, te desconectes, lo detengas o lo termine un límite. Si el navegador se cae, se conserva el estado guardado anterior en lugar de reemplazarlo por uno parcial. Las cookies de sesión (las que no tienen vencimiento) se descartan, igual que las descarta un navegador real al reiniciarse.
  • Hasta unos 3.5 MB comprimidos. Si el IndexedDB de un sitio lo hace más grande, el IndexedDB queda fuera; las cookies y el localStorage se siguen guardando.
  • Privado. Un perfil es solo tuyo (el “shop-account” de otro cliente es un perfil distinto), se almacena cifrado y solo se entrega al servidor que ejecuta tu sesión. Lístalos con GET /api/v1/browsers/profiles, borra uno con DELETE /api/v1/browsers/profiles/<name> o usa el panel.

¿Ya iniciaste sesión en otro lugar? La sincronización de cookies copia esas cookies a un perfil, así que la primera sesión también empieza con la sesión iniciada.

Fijar una versión

Las sesiones ejecutan la versión actual de Clearcote. Para ejecutar una anterior, pasa version: la versión completa ("156.0.8078.47-r51"), solo la recompilación ("r51"), una versión de Chromium o solo su versión mayor ("155" elige el build más reciente de esa versión), o "latest". Son las mismas versiones que descarga la opción version del SDK, así que una sesión alojada y una ejecución local fijadas a la misma versión usan el mismo 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 ... " ]
  • Revisa warnings. Una versión anterior no tiene lo que agregaron las versiones posteriores. Las opciones y correcciones que llegaron después pueden faltar, o ignorarse en silencio en lugar de rechazarse, así que un ajuste que funciona en la versión actual puede no hacer nada, sin avisar, en una versión fijada.
  • El engine de la respuesta siempre indica qué versión ejecuta la sesión, esté fijada o no.
  • Una versión que no existe da un 400 con el código UNKNOWN_VERSION, y el mensaje lista las versiones que puedes elegir.
  • La primera sesión con una versión que nuestros servidores todavía no han usado puede tardar hasta un minuto más en iniciar mientras se descarga el build. Las siguientes sesiones con esa versión arrancan tan rápido como cualquier otra.

Página de inicio y bloqueo de anuncios

  • url abre una página en la primera pestaña antes de que te conectes, así que ya está cargando cuando tu script se conecta.
  • adblock: true rechaza las solicitudes a hosts conocidos de anuncios, de verificación de anuncios y de analítica antes de que se hagan, así que nunca se facturan. La lista es deliberadamente conservadora (no toca los gestores de etiquetas, las herramientas de consentimiento, los SDKs de login ni los CAPTCHAs), pero algunos sitios notan que faltan anuncios; déjalo desactivado donde eso importe.