オプションとアイデンティティ
ホスト型ブラウザを起動するときに設定できるもの:オプション、ステルスのデフォルト設定とアイデンティティ、ログイン状態を保つプロファイル、固定するリリース、開始ページ。
オプション
すべて省略可能です。作成リクエストの 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 マシン上で動いているため、裏付けられるのはその OS です)、lightStealth の有効化、シード、出口 IP に合わせたタイムゾーンと言語(自前のプロキシでも当社のプロキシでも同じです)、Google Chrome が備えている Widevine モジュール(これにより requestMediaKeySystemAccess("com.widevine.alpha") が成功します)、そして人間らしいマウスの動き(後述)です。lightStealth(デフォルト)では、CPU コア数、メモリ、ピクセル比を変えた少数のデバイスプロファイルの中から、シードが 1 つを選びます。canvas、WebGL、オーディオは、セッションが動作しているマシンで描画されます。セッションが WebGL に報告するグラフィックスカードは、そのマシンと同じクラスの実在するモデルの中からセッションごとに選ばれ、同じ identity は同じカードを報告します。そのため、同じマシン上のセッションはそれぞれ異なるカードを報告し、WebGL の上限値や動画コーデックへの応答はそのカードと整合したまま保たれます。シードごとに完全なペルソナを使うには lightStealth: false を設定します。この場合、canvas と WebGL の読み取り結果にはシードに基づくサイトごとのノイズが加わり、GPU 文字列、画面、オーディオ設定(サンプルレート、レイテンシ)はペルソナに従います。identity も fingerprint も指定しない場合、セッションごとにランダムなシードと新しい IP が割り当てられます。
identity: "account-42" を渡すと、以降のセッションでも同じデバイスプロファイルで、しかもその住宅用 IP がオンラインである限り同じ IP で戻ってこられます。ログイン済みのアカウントにとっては、これが自然な状態です。アイデンティティはアカウント単位で非公開です。別の顧客が同じラベルを使っても、その顧客には別のシードと IP が割り当てられます。アイデンティティだけでは Cookie は保持されません。Cookie を保持するにはプロファイルを使ってください。
人間らしい入力
素の Playwright と Puppeteer は、マウスを一度に飛ばして動かします。1 回の移動でターゲットに到達し、その 1〜2 ミリ秒後にクリックが続きます。ホスト型ブラウザは、どのクライアントからの操作でも、サーバー側(ブラウザのすぐ隣)でこれをなめらかにします。移動やクリックの位置が現在のカーソル位置から離れている場合、サーバーはまず人の手のようにカーソルをそこまで動かし(曲線を描き、実際に手を伸ばすときの速さと小さな修正を伴って)、そのあとでイベントを届けます。ボタンは、手が落ち着くのと同じように、カーソルが到着してから少し間を置いて押されます。各クリックは、人が押すのと同じくらいの時間押されたままになってから離されます。1 つのアイデンティティは 1 つの動き方を保ちます。スクリプトの変更は不要で、クリック 1 回あたり約 1 秒遅くなります。
スクロールも同じように扱われます。ホイール 1 ノッチ(ブラウザが動いている Windows マシンでは 100 px)を超えるスクロールは、指でホイールを回すときのように、短いまとまりに分けたノッチ単位で届きます。カーソルが別の場所にある場合は、先にスクロール位置まで移動します。ページは指定した距離をちょうどスクロールし(端数は最後のノッチに含まれます)、最後のノッチが送られた時点で呼び出しが戻ります。
次の入力は、送ったとおりそのまま渡されます。数ピクセルの移動(SDK 自身の humanize のように、すでに細かいステップで動かすクライアント)、ボタンを押したままのドラッグ、1 ノッチ以下のスクロール、タッチ、キーボードです。素の速度が必要な場合は humanize: false を渡してください。
プロファイル:ログインは一度だけ
プロファイルはセッションの Cookie、localStorage、IndexedDB を名前を付けて保存するため、同じ名前で次に起動したセッションはログイン済みの状態から始まります。profile: { name: "shop-account", persist: true } を渡すとプロファイルを読み込み、セッション終了時に書き戻します。profile: "shop-account" だけを渡すと、読み取り専用で読み込みます。新しい名前での最初のセッションは空の状態で始まり、そのプロファイルを作成します。
// 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:<name>)を持つため、サイトからは同じフィンガープリントに見え、その IP がオンラインである限り同じ住宅用 IP からのアクセスになります。再訪した顧客と同じ見え方です。別の設定にしたい場合はidentityまたはfingerprintを自分で渡してください。また、実行ごとに国を変えないようにしてください。 - 書き込めるのは同時に 1 セッションだけ。プロファイルに保存できる実行中のセッションは 1 つだけで、
persist: trueを指定した 2 つ目のセッションには409 PROFILE_IN_USEが返ります。読み取り専用のセッションは並行して実行でき、最後に保存された状態を参照できます。 - ブラウザを閉じた場合、切断した場合、停止した場合、制限によって終了した場合のいずれでも、セッション終了時に保存されます。ブラウザがクラッシュした場合は、不完全な状態で上書きせず、前回保存された状態を保持します。セッション Cookie(有効期限のないもの)は、実際のブラウザが再起動時に破棄するのと同じく破棄されます。
- 圧縮後で最大約 3.5 MB です。サイトの IndexedDB のせいでこれを超える場合は IndexedDB を除外しますが、Cookie と localStorage は引き続き保存されます。
- 非公開。プロファイルはあなた専用で(別の顧客の「shop-account」は別のプロファイルです)、暗号化して保存され、あなたのセッションを実行するサーバーにだけ渡されます。一覧の取得は
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には、そのセッションが実行しているリリースが常に示されます。 - 存在しないリリースを指定すると、コード
UNKNOWN_VERSION付きの400が返り、メッセージには選択可能なリリースが列挙されます。 - 当社のサーバーでまだ使われたことのないリリースで最初のセッションを起動すると、ビルドを取得するため、起動に最大 1 分ほど余計にかかることがあります。それ以降のセッションは、ほかと同じ速さで起動します。
開始ページと広告ブロック
urlを指定すると、接続前に最初のタブでページが開かれます。そのため、スクリプトが接続した時点ですでに読み込みが始まっています。adblock: trueは、よく知られた広告、広告検証、アナリティクスのホストへのリクエストを送信前に拒否するため、それらが課金されることはありません。リストは意図的に控えめにしてあります(タグマネージャー、同意管理ツール、ログイン SDK、CAPTCHA には手を加えません)が、広告が表示されないことに気づくサイトも一部あります。それが問題になるサイトでは無効のままにしてください。