iframe 内の CAPTCHA が検出されない？正しいフレームを見つける方法

要約

• ブラウザ上ではCAPTCHAが見えていても、スクリプトは別のドキュメントを探索している場合がある。
• 最上位ページ、埋め込みアプリケーションのフレーム、CAPTCHAプロバイダ自身のウィジェットフレームを区別する。
• 適切なコンテキストを調査するために、使用している自動化フレームワークの公式フレームAPIを使う。
• ページURLとsitekeyは同じCAPTCHAインスタンスに紐づける。iframeのリソースURLは、自動的にソルバーに渡すべきwebsiteURLになるわけではない。
• フレームを見つけることやsitekeyを読むことは「検出」であり、CAPTCHAの解決やフォーム送信の成功ではない。

ブラウザのスクリーンショットではCAPTCHAが表示されているのに、自動化ではウィジェットが見つからないことがある。そのとき役に立つ次の確認ポイントは「ドキュメントコンテキスト」だ。トップレベルページでセレクタを評価しても、すべての埋め込みドキュメントが自動的に検索されるわけではない。また、通常のページJavaScriptには、別オリジンのフレームに対して制限がある。

CapSolver にリクエストを送る前に、どのページがチャレンジを所有していて、そのパラメータがどこから来ているかを特定する。このガイドでは、壊れやすい内部セレクタに依存したり、ブラウザのフレームにアクセスできることをチャレンジ解決の証拠とみなしたりせずに、その調査ステップを説明する。

見えているCAPTCHAが見逃される理由

見えているCAPTCHAが見逃されるのは、「画面上の見た目の構成」と「ドキュメント構造」が別物だからだ。

ブラウザは複数のドキュメントを一つのウィンドウに描画する。一方、自動化側は、調べたい要素を含むドキュメントに対して処理を行う必要がある。トップページがアプリケーションを埋め込み、そのアプリケーションがさらに別のフレーム経由でCAPTCHAを描画することもある。

ブラウザの同一オリジンポリシーは、ページのJavaScriptが別オリジンをまたいで読み出せる範囲を制限する。そのため、親ドキュメントで動くスクリプトは、子ドキュメントを直接調べられない場合がある。この制限は、セレクタの不具合やソルバーの未対応とは別の問題だ。

CAPTCHA検出は、あくまで特定の観察結果として扱う。スクリーンショットは「ウィジェットらしきものが見えている」ことを示すにすぎない。フレーム検索は「埋め込みドキュメントが存在する」ことを示すにとどまる。どちらの観察も、それ単体ではソルビングタスクに必要な完全かつ最新のパラメータ一式を与えてはくれない。

ソルバーを変える前にページ構造をマッピングする

APIのペイロードを変更したりリトライ回数を増やしたりする前に、ドキュメント階層をマッピングする。

まずブラウザのトップレベルURLから始める。埋め込みアプリケーションのフレームと、その内部のCAPTCHAウィジェットを特定する。アプリケーションフォームを含むドキュメント、ウィジェットを描画するフレーム、そしてアプリケーションが検証結果を受け取る場所を記録する。

典型的な埋め込みワークフローでは、「アプリケーションフレーム」と「プロバイダのウィジェットフレーム」を区別することが重要だ。アプリケーションはユーザーが完了しようとしているタスクを所有している。一方、プロバイダフレームは自前の描画リソースやコントロールを含んでいる可能性がある。ソルバーの各リクエストでプロバイダフレームのリソースURLをコピーするだけでは、「CAPTCHAを利用しているページ」を正しく特定したことにはならない。

タスクパラメータ を、「ソルバーが何を期待しているか」の根拠として用いる。埋め込み構成のせいで正しいページコンテキストが不明瞭な場合は、アプリケーション自身の設定を確認するか、マスクした例を添えてサポートに問い合わせる。一つのスクリーンショットから、汎用的なURLルールを導き出そうとしてはいけない。

ウィジェットとそのパラメータをひとまとめに保つ

検出したsitekey、CAPTCHAファミリー、ページコンテキスト、タスク固有で必要なフィールドは、一つのウィジェットインスタンスに紐づけて管理する。

ページには複数のフォームやウィジェットが存在しうる。無関係なフレームから読み取ったキーは、一見有効そうに見えても、別のチャレンジを指している可能性がある。ナビゲーションやウィジェットの差し替えが起きた後は、過去のドキュメントから取っておいたデータを使い回すのではなく、関連する調査をやり直す。

これが、トップドキュメントでの検索結果が空だからといって、すぐにソルブを走らせるべきでない理由でもある。まずはチャレンジが別フレームにあるのか、まだロード中なのか、あるいは現在の状態では存在しないのかを確認する。

フレーム制御はフレームワークの機能を使う

別オリジンのフレームを親ページのJavaScriptから無理に読み出そうとするのではなく、ブラウザ自動化ライブラリが提供するフレーム制御を使う。

Playwrightのフレームガイドでは、ページレベルの操作とフレーム内の操作が区別されている。フレームロケータを使うことで、テストは埋め込みドキュメント内のコンテンツを操作できる。フレームを選ぶ際には、単なるリスト内の数値的な位置ではなく、ページ上で検証可能な安定したプロパティを用いる。

Seleniumは異なる操作モデルを採用している。フレームに関するドキュメントでは、ドライバーのコンテキストをフレームに切り替え、再びデフォルトドキュメントに戻す方法が説明されている。CAPTCHAフレーム内にとどまり続けるテストは、その後アプリケーション側の送信ボタン（フレーム外）を見つけられずに失敗する場合がある。

これらはあくまで「ドキュメント間のナビゲーション手段」であって、CAPTCHAの解決機能ではない。フレームの調査、ソルバーへのリクエスト、アプリケーション側の処理継続は別々のステップとして扱い、失敗したときにどこで問題が起きたかを切り分けられるようにする。

CapSolverボーナスコードを利用する

自動化予算を即時にブースト！
入金時にボーナスコード CAP26 を使用すると、すべてのチャージに対して 5% 追加ボーナス を無制限で獲得できます。
今すぐ CapSolverダッシュボード で引き換えましょう。

検出失敗と決めつける前にロードと差し替えを確認する

関連するドキュメントとウィジェットのロードが完了しているかどうかを確認してから、検出結果が空であることを解釈する。

フレーム要素は、中身が準備できる前に存在しうる。またアプリケーションは、ルート変更後にフレームを差し替えたり、前回の試行後にウィジェットをリフレッシュしたりすることがある。その場合、以前に取得した参照は、もはや画面上に表示されているチャレンジを表していないコンテキストを指し続ける。

アプリケーション固有の「準備完了条件」を用いること：想定するフレームが存在し、目的のドキュメントがロード済みであり、関連するCAPTCHA設定が利用可能になっている、などだ。いたるところにsleepを増やすとテストは遅くなるが、これらの条件のいずれも満たされたと証明してはくれない。

reCAPTCHA判別ガイド は、タスク選択前にバージョンを見分ける助けになる。その判別結果は、目に見えるボックスのサイズや位置から推測するのではなく、現在のフレームコンテキストと組み合わせて使う。

もしプロバイダのスクリプト自体がロードに失敗しているなら、そのロード失敗を調査すること。ページデータが不完全または古い状態のままそれをもとにソルバーリクエストを組み立てても、「ウィジェットスクリプトが読み込めない」という問題の解決にはならない。

検証済みの入力を、対応するソルバーインターフェースへ渡す

自分のワークフローに合ったソルバーインターフェースを通じて入力を渡し、そのインターフェースのフレームサポートを「仮定する」のではなく実際に確認する。

Core SDKガイド には、サポートされているブラウザ連携方法およびCAPTCHA情報の取得方法が記載されている。インストールしているバージョンに対して、その契約に従う。pageオブジェクトを受け取るメソッドであっても、すべてのフレーム、ラッパー、リモートハンドル、ブラウザライブラリのオブジェクトを受け付けると明示されているわけではない。

REST APIを使う場合は、対応するタスクリファレンスが要求するフィールドを、許可されたページおよびその設定から収集する。URL、公開sitekey、チャレンジのバリアントの元々の関係性を保ったままにする。同じ名前のフィールドだからといって、別タブで集めた値を混在させない。

トークンを結果として受け取る場合も、アプリケーション側との連携が必要だ。返されたトークンは、有効なうちに正しいアプリケーションフローへ届けなければならない。無関係なドキュメントに書き込まれたり、フレームのリロード時に破棄されたりした結果は、成功とは見なせない。

プロバイダ所有のウィジェット内部を、一般的なテクニックとして書き換えることは避ける。内部マークアップは変更されうるし、textareaやボタンを見つけたとしても、アプリケーション側でドキュメント化された検証フローがどう動いているかは分からない。必要な操作については、公式のソルバーおよびアプリケーションインターフェースを優先する。

CAPTCHA後のページ結果を検証する

ワークフローが続行するコンテキストで、アプリケーションの結果を検証する。

意図したCAPTCHA操作を終えたら、フレームワークがコンテキストを切り替えていた場合はアプリケーションドキュメントに戻る。所有するフォームの確認状態など、タスクが期待する具体的な結果を確認する。検出されたiframe、空でないトークン文字列、ボタンのクリックを、「アプリケーション側での受理」と同等とみなしてはいけない。

有用な失敗記録を残すには、最上位URL、関連するフレーム関係、CAPTCHAファミリー、失敗したステージ、およびマスクしたエラー説明を保存する。セッションの秘密情報や無関係なページ内容は含めない。

この小さな記録があれば、フレーム選択のミス、ロードの問題、パラメータ不一致、ソルバーの失敗、アプリケーション側での拒否を区別できる。それぞれが必要とする修正は異なる。

CapSolverで信頼性の高い自動化ワークフローを構築する

むやみにソルブ試行を繰り返す前に、ドキュメントコンテキストを整理する。CapSolver には、実際のチャレンジを正しく表現する入力とブラウザ連携が必要だ。明確なフレームマップを持つことで、これらの入力を検証しやすくなり、検出と最終的なアプリケーション結果を分離して考えられるようになる。

FAQ

Q: document.querySelectorはすべてのiframeの中まで検索しますか？

いいえ。クエリは、現在のドキュメントコンテキスト内でのみ実行される。ターゲット要素が埋め込みドキュメントに属する場合は、自動化フレームワークのフレーム機能を使う。

Q: websiteURLはCAPTCHA iframeのsrcにすべきですか？

自動的にそうとは限らない。プロバイダのリソースURLは、必ずしも「CAPTCHAを利用しているページ」とは限らない。対応するタスクリファレンスに従い、アプリケーションコンテキストを確認すること。

Q: Seleniumでウィジェットは見つかるのに、その後フォームのボタンが見つからないのはなぜですか？

ドライバーがまだフレームコンテキスト内にいる可能性がある。フォームボタンを所有しているドキュメントを確認し、操作前にドキュメント化されたコンテキスト切り替えを行う。

Q: sitekeyを見つけたらCAPTCHAは解決済みということですか？

いいえ。公開sitekeyは、CAPTCHA設定を識別する入力にすぎない。検出、ソルブ、そしてアプリケーションによる結果の検証は別々のステージだ。

Q: ページSDKのメソッドは、常にフレームオブジェクトを受け付けますか？

いいえ。インストールされているSDKについて、ドキュメント化されている型のオブジェクトだけを渡すこと。見た目が似たメソッドインターフェースであっても、それだけで互換性があるとは限らない。