跳到正文

选项与身份

启动托管浏览器时可以设置的内容:各项选项、默认隐匿设置与身份、让你保持登录的 Profile、固定版本和起始页。

选项

以下选项均为可选,作为创建调用的 JSON 请求体发送。

字段类型含义
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.

默认隐匿设置与身份

每个会话都以推荐设置页面中的配置为起点: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。

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" }),
});
  • 同一设备,同一 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 选项下载的是同一批,因此固定到同一版本的托管会话和本地运行使用的是同一个构建。

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 ... " ]
  • 检查 warnings。旧版本不具备后续版本新增的内容。在它之后才加入的选项和修复可能缺失,或者被静默忽略而不是报错拒绝,因此在当前版本上有效的设置,在固定的旧版本上可能悄无声息地不起任何作用。
  • 无论是否固定版本,响应中的 engine 都会说明会话运行的是哪个版本。
  • 指定不存在的版本会返回 400,错误码为 UNKNOWN_VERSION,错误信息中会列出可选的版本。
  • 如果某个版本我们的服务器还没有用过,该版本上的第一个会话在获取构建期间,启动时间最多可能多出一分钟。之后该版本上的会话启动速度与其他会话一样快。

起始页与广告拦截

  • url 会在你连接之前就在第一个标签页中打开一个页面,这样你的脚本接入时,页面已经在加载了。
  • adblock: true 会在请求发出之前拒绝发往知名广告、广告验证和统计分析主机的请求,因此这些请求不会计费。该列表刻意保持保守(标签管理器、授权同意工具、登录 SDK 和 CAPTCHA 都不受影响),但少数网站会察觉到广告缺失;在这类场景下请保持关闭。