选项与身份
启动托管浏览器时可以设置的内容:各项选项、默认隐匿设置与身份、让你保持登录的 Profile、固定版本和起始页。
选项
以下选项均为可选,作为创建调用的 JSON 请求体发送。
| 字段 | 类型 | 含义 |
|---|---|---|
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. |
默认隐匿设置与身份
每个会话都以推荐设置页面中的配置为起点:Windows 身份画像(浏览器运行在 Windows 机器上,所以这是它们能够真实支撑的系统)、开启 lightStealth、一个种子(seed)、跟随出口 IP 的时区和语言(无论使用你自己的代理还是我们的代理)、Google Chrome 自带的 Widevine 模块(因此 requestMediaKeySystemAccess("com.widevine.alpha") 可以成功),以及拟人化的鼠标移动(见下文)。在 lightStealth(默认)模式下,种子会从一小组设备配置中选出一个,这些配置在 CPU 核心数、内存和像素比上各不相同;canvas、WebGL 和音频由会话所在的机器渲染。会话向 WebGL 报告的显卡,会为每个会话从与该机器同类的一系列真实型号中选取,同一个 identity 报告同一张显卡,因此同一台机器上的会话报告不同的显卡,而 WebGL 限制值和视频编解码器的应答与之保持一致。设置 lightStealth: false 可获得完整的、按种子生成的身份画像(persona):canvas 和 WebGL 的像素读回会带上由种子派生、按站点区分的噪声,GPU 字符串、屏幕和音频设置(采样率、延迟)也都跟随身份画像。如果不指定 identity 或 fingerprint,每个会话都会得到一个随机种子和一个新 IP。
传入 identity: "account-42",之后的会话就会以同一个设备配置回来,并且只要该住宅 IP 仍然在线,就使用同一个 IP——这正是已登录账号所期望的。身份只在你的账号内有效:其他客户即使使用相同的标签,也会得到他们自己的种子和 IP。身份本身不会保留 cookie;如需保留,请使用 Profile。
拟人化输入
原生的 Playwright 和 Puppeteer 移动鼠标是一步到位的:一次移动直接落到目标上,点击在一两毫秒内紧随其后。托管浏览器在服务器端、紧挨着浏览器的地方把这一过程变得平滑,对任何客户端都有效:当一次移动或点击落在离光标当前位置较远的地方时,服务器会先像人手那样把光标移过去(走曲线,带有真实伸手动作的速度和细小修正),再投递你的事件。光标到达后会稍等片刻才按下,就像手先稳住一样;每次点击都会按住一段人按下按键的时长后再松开。同一个身份始终保持同一种移动方式。你的脚本无需任何改动,每次点击大约会慢一秒。
滚动也按同样的方式处理。超过一格滚轮刻度的滚动(在运行浏览器的 Windows 机器上为 100 px)会以整格的形式分成几阵短促地送达,就像手指拨动滚轮一样;如果光标在别处,会先移到滚动位置。页面滚动的距离与你请求的完全一致,余数由最后一格带上,最后一格发出后你的调用才返回。
以下输入会按你发送的原样保留:几个像素的移动(已经以小步移动的客户端,例如 SDK 自带的 humanize)、按住按键的拖拽、不超过一格的滚动、触摸和键盘。需要原始速度时,传入 humanize: false。
Profile:只需登录一次
Profile 会以一个名称保存会话的 cookie、localStorage 和 IndexedDB,之后使用该名称的会话启动时就已处于登录状态。传入 profile: { name: "shop-account", persist: true } 会加载它,并在会话结束时保存回去;只传 profile: "shop-account" 则以只读方式加载。使用新名称的第一个会话从空白状态开始,并创建该 Profile。
// 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" }),
});- 同一设备,同一 IP。Profile 自带身份(
profile:<name>),因此站点看到的是同一个指纹;只要该住宅 IP 仍在线,看到的也是同一个 IP,就像一位回头客。如需另作选择,可自行传入identity或fingerprint,并在多次运行之间保持国家不变。 - 同一时间只有一个写入者。同一 Profile 只允许一个正在运行的会话写入;第二个带
persist: true的会话会收到409 PROFILE_IN_USE。只读会话可以同时运行,看到的是最后一次保存的状态。 - 在会话结束时保存,无论是你关闭浏览器、断开连接、停止会话,还是因达到某项限制而结束。如果浏览器崩溃,会保留上一次保存的状态,而不会被不完整的状态覆盖。会话 cookie(没有过期时间的 cookie)会被丢弃,就像真实浏览器重启时会丢弃它们一样。
- 压缩后最多约 3.5 MB。如果某个站点的 IndexedDB 使其超出这一大小,IndexedDB 将不予保存;cookie 和 localStorage 仍会保存。
- 私有。Profile 只属于你(其他客户的“shop-account”是另一个 Profile),加密存储,并且只会交给运行你会话的服务器。用
GET /api/v1/browsers/profiles列出,用DELETE /api/v1/browsers/profiles/<name>删除,也可以使用仪表盘。
已经在别处登录了?Cookie 同步会把这些 Cookie 复制到配置文件中,这样第一个会话一开始就是登录状态。
固定版本
会话运行的是当前的 Clearcote 版本。要运行旧版本,请传入 version:可以是完整版本号("156.0.8078.47-r51")、仅重建编号("r51")、Chromium 版本号或主版本号("155" 会选择该主版本的最新构建),或 "latest"。这些版本与 SDK 的 version 选项下载的是同一批,因此固定到同一版本的托管会话和本地运行使用的是同一个构建。
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 ... " ]- 检查
warnings。旧版本不具备后续版本新增的内容。在它之后才加入的选项和修复可能缺失,或者被静默忽略而不是报错拒绝,因此在当前版本上有效的设置,在固定的旧版本上可能悄无声息地不起任何作用。 - 无论是否固定版本,响应中的
engine都会说明会话运行的是哪个版本。 - 指定不存在的版本会返回
400,错误码为UNKNOWN_VERSION,错误信息中会列出可选的版本。 - 如果某个版本我们的服务器还没有用过,该版本上的第一个会话在获取构建期间,启动时间最多可能多出一分钟。之后该版本上的会话启动速度与其他会话一样快。
起始页与广告拦截
url会在你连接之前就在第一个标签页中打开一个页面,这样你的脚本接入时,页面已经在加载了。adblock: true会在请求发出之前拒绝发往知名广告、广告验证和统计分析主机的请求,因此这些请求不会计费。该列表刻意保持保守(标签管理器、授权同意工具、登录 SDK 和 CAPTCHA 都不受影响),但少数网站会察觉到广告缺失;在这类场景下请保持关闭。