本文へスキップ

チャレンジ

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

スライダーチャレンジ

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

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

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

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

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

長押しチャレンジ

一部のサイトは「長押し」の確認ボタンを表示します。ボタンを十分な時間押し続けるとチェックが通ります。ホスト型ブラウザは、どのタブでもフレーム内でも、別サイトのフレームやボタンをページのスクリプトから隠すウィジェットも含めて、このボタンを代わりに押し続けます。スライダーやチェックボックスとは別の独立したオプションで、これも既定でオンです。これらのボタンをスクリプト側で扱う場合は solvePressHold: false を渡してください(たとえば 長押し を使う場合)。自分で起動したブラウザが自動でこれを行うことはありません。

  • 押し続け方。人間らしい速さでポインターをボタンまで動かし、短く間を置いてから押し、ボタンが完了を示すまで押し続け、人間らしい遅れで離します。
  • 確認できること。各試行はセッションのイベントタイムラインに pressHold イベントとして記録されます。ボタンが完了を示した場合は passed、示さなかった場合は failed(時間切れになった長押しの理由は timeout)、理由付きで見送った場合は skipped です。
  • 処理の順序。スライダー、チェックボックス、長押しボタンの順です。それぞれに個別のスイッチがあり、1つをオフにしても他はオンのままです。

チャレンジ解決サービス

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

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

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

カテゴリー該当するものauto に含まれるか
tokenページにトークンを渡すウィジェット。画像パズルに変わる「私はロボットではありません」のボックス、パズルが表示される不可視のウィジェット、応答されないまま残る対話型の「人間であることを確認してください」チェックです。はい
clearance自動では解除されない、ページ全体の「ブラウザを確認しています」という待機画面。はい
block-pageパズルやデバイスチェックを含む、サイトのブロックページ。はい
imageテキストボックスの横にある歪んだ文字のコードと、ブラウザが自分で欠けた位置を見つけられなかったジグソーパズル。はい
scoreページ自体が実行する不可視のスコアチェック。いいえ:自分で指定します
  • 自動選択。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 と解決できるかどうかとともに表示されます。その後、そのサイトに対して該当するカテゴリーだけを有効にします。
javascript
// 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" }

すべてのフィールド

フィールド型デフォルト意味
categories"auto"、または token、score、clearance、block-page、image のリスト"auto"どの種類のチャレンジに答えてよいか。auto は score 以外のすべてです。
sitesホスト名のリストすべてのサイトこれらのホストとそのサブドメインでのみ有効です(最大 50 個)。
key"own" または "managed"保存済みのキーがあればそれ、なければ当社のキーどちらの解決サービスのキーを使うか。自分のキーか、当社のキー(解決したチャレンジごとに課金)です。
apiKey文字列なしこのセッションだけに使う自分の解決サービスのキー(暗号化して保存され、二度と表示されません)。key: "own" を指定したものとみなされます。
mode"solve" または "report""solve"report は認識して報告するだけです。何も依頼せず、何も支払わず、キーも不要です。
maxSolves整数、1~10010セッションあたりの依頼回数。この回数に達すると依頼を止めます。
maxSpendEur数値、0.01~1000.50セッションが解決に使える金額(当社のキーでは、支払う金額)。そこに達すると依頼を止めます。

仕組み

  • まず無料の操作から。スライダーとチェックボックスの操作が常に先に行われます。サービスに依頼するのは、十分な機会を与えた後もチャレンジが残っている場合だけです。具体的には、画像パズルが表示された、不可視のウィジェットがパズルを開いた、ウィジェットが約 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 として報告され、料金はかかりません。ページのアドレスとチャレンジの詳細は解決サービスに送信されます。

料金

  • 自分のキーを使う場合:当社からの請求はありません。解決サービスにその料金で直接支払います。ホスト型ブラウザの残高から差し引かれるのは、ほかのセッションと同じくトラフィック分だけです。
  • 当社のキーを使う場合:解決したチャレンジごとに、ホスト型ブラウザの残高から差し引きます。そのチャレンジに対する解決サービスの料金(USD)を、1 $ あたり 0.92 € で換算し、× 1.5 した額です。失敗した試行、見送ったチャレンジ、mode: "report" は無料です。月額料金はなく、申し込みも不要です。
  • 正確な料金は、チャレンジが解決されて初めてわかります。料金はチャレンジの種類によって異なり、サービスはそれぞれを、対応できる複数のソルバーのうち最も安いものに送ります。以下は、当社のキーで課金される場合の種類ごとの見積もりです。通常は最も安いソルバーの料金で、これまでの当社での解決はこの料金でした。最大は、最も安いソルバーが対応できない場合に備えた、その種類についてサービスが掲載している最も高いソルバーの料金です。
ページ上の表示カテゴリー通常(1,000 回あたり)通常(1 回あたり)最大(1,000 回あたり)
“I’m not a robot” box with a picture puzzle (the most common widget)token€0.18€0.00018€4.13
The same widget’s enterprise editiontoken€0.18€0.00018€6.90
Interactive “verify you are human” checktoken€0.14€0.00014€2.76
Other picture-puzzle widgets, visible or invisibletoken€0.95€0.00095€9.66
Their enterprise editionstoken€2.76€0.0028€13.80
Smaller token widgets (proof-of-work, puzzle and regional widgets)token€1.10€0.0011€4.14
Invisible score check, standard or enterprisescore€0.72€0.00072€6.90
Full-page “checking your browser” waitclearance€0.28€0.00028€1.79
Block page with a slider or a device checkblock-page€0.83€0.00083€3.81
Block page with a puzzle from a cloud firewallblock-page€0.69€0.00069€2.76
Distorted-text codeimage€0.14€0.00014€0.55
Jigsaw whose gap the browser could not placeimage€1.66€0.0017€2.76
  • 実際の目安。最も一般的なウィジェットを 1,000 回解決すると、通常は約 €0.18 です。全画面の待機を同じ回数行うと約 €0.28 です。サイトがトークンを拒否した場合は、セッションの IP を通じてもう一度だけ依頼するため、1 つのチャレンジが 2 回課金されることはありますが、それ以上になることはありません。
  • 料金は 2026-10-13 時点のサービスの料金表に基づき、サービス側が変更すれば変わります。一部のソルバーはチャレンジの難しさに応じて料金を決めます。最大にはその範囲の上限を使っています。
  • 各解決の正確な費用は、その challenge.service イベント (costUsd。換算と上乗せ前のサービスの料金)に記録されます。セッションの challenges.costEur(GET /api/v1/browsers/<id> 内)は、それらに対して請求された合計額です。
  • 1 セッションで使える上限。デフォルトでは、セッションは 10 回の依頼か €0.50 のどちらか先に達した時点で止まります。10 回の解決は通常 €0.03 未満で、上の最も高い料金でも約 €0.14 です。maxSolves と maxSpendEur で上げ下げできます。アカウントごとの月間上限 (最大 €25)は、すべてのセッションを合わせた額に適用されます。

種類ごとに何が起きるか

ページ上の表示カテゴリーサービスに依頼するもの答えの入れ方
クリックすると画像パズルが開いた「私はロボットではありません」のボックスtokenそのウィジェット用のトークンウィジェットの応答フィールドに入れ、それを渡してページのコールバックを呼び出します
画像パズルが表示された不可視のウィジェットtokenそのウィジェット用のトークン同上
応答されないまま残る、対話型の「人間であることを確認してください」チェックtokenそのウィジェット用のトークン同上
テキストボックスの横にある歪んだ文字のコードimage画像内の文字ボックスをクリックしてから、キーを 1 つずつ押して入力します
ブラウザが自分では位置を合わせられないジグソースライダー(例:おとりの穴があるもの)image欠けている位置ブラウザがピースをそこまでドラッグし、実際にどこに収まったかを確認します
自動では解除されない、ページ全体の「ブラウザを確認しています」という待機画面clearanceセッションの出口 IP を通じて解決した clearance Cookieサイトに設定してから、ページを再読み込みします
パズルやデバイスチェックを含むブロックページblock-pageセッションの出口 IP を通じて解決した Cookieサイトに設定してから、ページを再読み込みします
ページ自体が実行する不可視のスコアチェック(score を指定した場合のみ)scoreページ自身のアクション用のスコアトークントークンを求めるページ自身の呼び出しに渡します

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

SDK から使う

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

typescript
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 }
python
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"])