オプションとアイデンティティ

ホスト型ブラウザを起動するときに設定できるもの：オプション、ステルスのデフォルト設定とアイデンティティ、ログイン状態を保つプロファイル、固定するリリース、開始ページ。

オプション

すべて省略可能です。作成リクエストの JSON ボディとして送信します。

ステルスのデフォルト設定とアイデンティティ

すべてのセッションは「推奨設定」ページの設定から始まります。つまり lightStealth が有効で、シードが割り当てられ、タイムゾーンと言語は出口 IP に合わせられます。lightStealth（デフォルト）では、CPU コア数、メモリ、ピクセル比を変えた少数のデバイスプロファイルの中から、シードが 1 つを選びます。canvas、WebGL、オーディオは、セッションが動作しているマシンのものがそのまま使われます。シードごとに完全なペルソナを使うには lightStealth: false を設定します。この場合、canvas と WebGL の読み取り結果にはシードに基づくサイトごとのノイズが加わり、GPU 文字列、画面、オーディオ設定（サンプルレート、レイテンシ）はペルソナに従います。identity も fingerprint も指定しない場合、セッションごとにランダムなシードと新しい IP が割り当てられます。

identity: "account-42" を渡すと、以降のセッションでも同じデバイスプロファイルで、しかもその住宅用 IP がオンラインである限り同じ IP で戻ってこられます。ログイン済みのアカウントにとっては、これが自然な状態です。アイデンティティはアカウント単位で非公開です。別の顧客が同じラベルを使っても、その顧客には別のシードと IP が割り当てられます。アイデンティティだけでは Cookie は保持されません。Cookie を保持するにはプロファイルを使ってください。

プロファイル：ログインは一度だけ

プロファイルはセッションの 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 を渡します。指定できるのは、完全なリリース名（"152.0.7977.82-r21"）、リビルド番号のみ（"r21"）、Chromium のバージョンまたはメジャーバージョン（"152" ならその最新ビルドが選ばれます）、または "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: "152.0.7977.82-r21" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "152.0.7977.82", revision: "r21", pinned: true }
// warnings -> [ "This session runs 152.0.7977.82-r21, older than the current ... " ]

• warnings を確認する。古いリリースには、それ以降のリリースで追加されたものが含まれていません。後から追加されたオプションや修正は存在しないか、拒否されずに黙って無視されることがあります。そのため、現行リリースで機能する設定が、固定したリリースでは何の効果もないまま終わる可能性があります。
• 固定しているかどうかにかかわらず、レスポンスの engine には、そのセッションが実行しているリリースが常に示されます。
• 存在しないリリースを指定すると、コード UNKNOWN_VERSION 付きの 400 が返り、メッセージには選択可能なリリースが列挙されます。
• 当社のサーバーでまだ使われたことのないリリースで最初のセッションを起動すると、ビルドを取得するため、起動に最大 1 分ほど余計にかかることがあります。それ以降のセッションは、ほかと同じ速さで起動します。

開始ページと広告ブロック

• url を指定すると、接続前に最初のタブでページが開かれます。そのため、スクリプトが接続した時点ですでに読み込みが始まっています。
• adblock: true は、よく知られた広告、広告検証、アナリティクスのホストへのリクエストを送信前に拒否するため、それらが課金されることはありません。リストは意図的に控えめにしてあります（タグマネージャー、同意管理ツール、ログイン SDK、CAPTCHA には手を加えません）が、広告が表示されないことに気づくサイトも一部あります。それが問題になるサイトでは無効のままにしてください。