チャレンジ

ホスト型ブラウザは、スライダーとチェックボックスのチャレンジを自動で処理します。チャレンジ解決サービスは指定しない限りオフで、ブラウザだけでは処理できないものを引き受けます。

スライダーチャレンジ

サイトによっては「スライドして認証」タイプのチャレンジを返します。バーの端までハンドルをドラッグするもの、 またはパズルのピースを欠けた位置までドラッグするものです。ホスト型ブラウザはこれを自動で処理します。どのタブでも、 フレームの中でも動作します。デフォルトで有効です。スクリプト側で処理する場合は solveSliders: false を渡してください。

• 何をするか。通常のスライダーは端までドラッグします。パズルはピースが欠けた位置に収まるまで ドラッグします。ブラウザはパズル画像の中で欠けた位置を見つけ、ピースが実際にどこへ動いたかを確かめて補正します。 ドラッグはボタンを押したまま人間のペースで動かす操作で、瞬間移動ではありません。
• 手を出さない場合。欠けた位置を確信を持って見つけられないときは、当て推量で動かさずにパズルを そのままにします。誤ったドラッグはセッションにとって不利に働くことがあるためです。試行は 1 ページにつき最大 3 回で、誰かがライブビューからセッションを操作している間や、引き継ぎ中は待機します。
• 確認できること。各試行はセッションのイベントタイムラインに slider イベントとして記録され、チャレンジがその後消えたか（passed）消えなかったか（failed）、 またはパズルに手を出さなかった理由（skipped）がわかります。
• 触れるのはチャレンジだけです。ページやその周りのウィジェットがそう示している場合（キャプチャや認証チェック） にのみ、スライダーをチャレンジとみなします。レンジ入力、カルーセル、価格フィルターには触れません。スクリプト自身の マウス操作と進行中のドラッグが混ざることがあるので、チャレンジが表示されている間はクリックを止めるか、 このオプションをオフにしてください。

チェックボックスチャレンジ

サイトによっては、最初に「人間であることを確認」のチェックボックスにチェックを求めます。ホスト型ブラウザはこれを 自動でクリックします。どのタブでも、フレームの中でも、ページのスクリプトからボックスを隠すウィジェットでも動作します。 スライダーとは別のオプションで、こちらもデフォルトで有効です。これらのボックスを自分で扱う場合は solveCheckboxes: false を渡してください。

• 対象のボックス。ボックス自体の文言が人間確認であることを示しているもの（人間、ロボット、キャプチャ、 確認してください…）だけです。「ログイン状態を保持」や「利用規約に同意する」のボックスは、ページの他の部分に何が 書かれていてもクリックしません。
• クリックの仕方。人間のペースでポインターをボックスまで動かし、少し間を置いてから、人のクリックと 同じくらいの長さで押します。その後ボックスがスライダーを開いた場合は、スライダーとして処理します。
• 確認できること。各試行はセッションのイベントタイムラインに checkbox イベントとして記録されます。ボックスが消えたかチェックされた場合は passed、まだ待っていた場合は failed です。試行は 1 ページにつき最大 3 回で、誰かがライブビューからセッションを操作している間や、 引き継ぎ中は行いません。

チャレンジ解決サービス

無料のスライダー操作とチェックボックス操作の後もチャレンジを出し続けるサイト向けに、ホスト型ブラウザはより難しいチャレンジを解決サービスに任せることができます。指定しない限りオフです。challengeService: true を渡して対象を自動で選ばせるか、オブジェクトを渡して何を許可するかを選びます。使うのは自分の解決サービスのキーか、当社のキー（解決したチャレンジごとに課金）です。

対応するチャレンジの選び方

サイトがどのウィジェットやどの提供元を使っているかを指定する必要はありません。ホスト型ブラウザはページ上の各チャレンジを、そのマークアップ、フレーム、動作から自分で認識し、5 つのカテゴリーのいずれかに分類します。選ぶのはウィジェットではなく、カテゴリーです。

• 自動選択。challengeService: true、または categories を含まない（あるいは categories: "auto" を指定した）オブジェクトでは、token、clearance、block-page、image のうち認識したすべてのチャレンジを、すべてのサイトで処理します。score が除外されるのは、ブラウザがすでに自分のスコアトークンを得ているためです。外部から答えると呼び出しのたびに解決 1 回分の費用がかかるので、自分のセッションのスコアを拒否するサイトでだけ指定する価値があります。
• カテゴリーを選ぶ。categories: ["token", "image"] は、それらだけを処理します。それ以外のカテゴリーのチャレンジもタイムラインには（category_off として）報告されますが、料金はかかりません。
• サイトを選ぶ。sites: ["shop.example"] は、対象をそれらのホストとそのサブドメインに限定します。それ以外の場所では何も報告せず、依頼もしません。categories と組み合わせると、「このサイトでこの種類のチャレンジ」という指定になります。
• サイトが何を使っているかわからない場合。まず mode: "report" で一度実行してください。何も依頼せず、何も支払いません。タイムラインには、ページに表示されたすべてのチャレンジが challenge.detected として、その category と解決できるかどうかとともに表示されます。その後、そのサイトに対して該当するカテゴリーだけを有効にします。

// In the body of POST /api/v1/browsers, or in the SDK's launch options (cloud: true)

// Auto-select: every challenge it recognises (all categories but score), on every site
challengeService: true

// Only widgets that hand out a token, only on one site, at most EUR 0.20 per session
challengeService: { categories: ["token"], sites: ["shop.example"], maxSpendEur: 0.2 }

// Only full-page waits and block pages, with your own solving-service key
challengeService: { categories: ["clearance", "block-page"], key: "own" }

// Auto-select plus the score check, on one site
challengeService: { categories: ["token", "clearance", "block-page", "image", "score"], sites: ["shop.example"] }

// First find out what a site uses: report only, nothing asked or paid for
challengeService: { mode: "report" }

すべてのフィールド

仕組み

• まず無料の操作から。スライダーとチェックボックスの操作が常に先に行われます。サービスに依頼するのは、十分な機会を与えた後もチャレンジが残っている場合だけです。具体的には、画像パズルが表示された、不可視のウィジェットがパズルを開いた、ウィジェットが約 15～25 秒応答されないままだった、ページ全体の待機画面が約 20 秒で解除されなかった、またはページがブロックページか文字コードである場合です。
• 答えの入れ方。ページが想定するとおりの方法で入れます。トークンはウィジェットの応答フィールドとそのコールバックへ、Cookie はサイトに設定して再読み込み、コードはそのボックスに入力、ジグソーはピースを所定の位置までドラッグします。その後、無料の操作と同じように、チャレンジが消えたことを確認します。
• 同じ IP。ページ全体の待機画面とブロックページは、答えを使う IP から解決する必要があります。サービスはセッション自身の出口 IP を通じて、短時間だけ使える使い捨ての接続でこれらを解決します。サイトに拒否されたトークンは、同じ方法でもう一度だけ依頼します。
• 自分のキーか当社のキーか。key: "own" は自分の解決サービスのキーを使います。キーはダッシュボード（Settings）で一度保存するか、リクエストで apiKey を渡します。キーは暗号化して保存され、二度と表示されず、ブラウザに渡ることもありません。料金はサービスに直接支払います。key: "managed" は当社のキーを使います。解決したチャレンジごとに、サービス自体の料金 × 1.5 がホスト型ブラウザの残高から差し引かれ、失敗した試行は無料です。key を省略すると、保存済みのキーがあればそれを、なければ当社のキーを使います。
• 制限。依頼はチャレンジごと・ページごとに最大 2 回です。セッションごとに maxSolves（デフォルト 10、最大 100）と maxSpendEur（デフォルト €0.50）があり、どちらかに達すると依頼を止めます。当社のキーでは、アカウントごとの月間上限もあります（ダッシュボードで設定、最大 €25）。キーが間違っている場合やサービス側の残高が空の場合は、そのセッションでの依頼を止めます。
• 確認できること。イベントタイムラインには、チャレンジごと・ページごとに一度の challenge.detected と、依頼ごとの challenge.service（solved、failed、skipped のいずれかと、その理由およびサービス側の費用）が記録されます。セッションには challenges（どちらのキーか、依頼回数、当社のキーでの解決にかかった費用）が記録されます。エージェント実行では、サービスがページを処理している間、エージェントは待機します。
• 一部のウィジェットは見つかっても解決されません。その答えを汎用的な方法でページに戻せないためです。これらは solvable: false として報告され、料金はかかりません。ページのアドレスとチャレンジの詳細は解決サービスに送信されます。

種類ごとに何が起きるか

無料の操作が引き続き先に行われます。普通のスライダーはドラッグし、ブラウザが欠けた位置を見つけられるジグソーは配置し、クリックでチェックが入るボックスはクリックします。いずれもサービスには依頼しません。ウィジェットでは、トークンを入れた後もボックス自体にはチェックが入らないままのことがあります。ページが読み取るのは応答フィールドとコールバックで、ボックスではありません。

SDK から使う

SDK 0.38.0 以降では、クラウドでの起動時にこのオプションを指定できます（Python では challenge_service で、max_solves、max_spend_eur、api_key も指定できます）。何が起きたかはタイムラインでわかります。最後のイベントはセッション終了の数秒後に届きます。

import { Cloud, launch } from "clearcote";

const browser = await launch({
  cloud: true,
  challengeService: { categories: ["token", "image"], sites: ["shop.example"], maxSpendEur: 0.2 },
});
const page = await browser.newPage();
await page.goto("https://shop.example/signup");
// ... your script: challenges the free actions cannot clear are answered for you
const id = browser.cloudSession.id;
await browser.close();

const { events } = await new Cloud().browsers.events(id);
for (const e of events) if (e.type.startsWith("challenge.")) console.log(e.type, e.data);
// challenge.detected { category: "token", solvable: true }
// challenge.service  { category: "token", outcome: "solved", applied: "callback", attempt: 1, ms: 12725, costUsd: 0.00013 }

from clearcote import Cloud, launch

browser = launch(cloud=True, challenge_service={"categories": ["token", "image"], "sites": ["shop.example"], "max_spend_eur": 0.2})
page = browser.new_page()
page.goto("https://shop.example/signup")
session_id = browser.cloud_session["id"]
browser.close()

for e in Cloud().browsers.events(session_id)["events"]:
    if e["type"].startswith("challenge."):
        print(e["type"], e["data"])