reCAPTCHAのコールバックを見つけてトークン処理を確認する方法

要約

• reCAPTCHA のコールバックは、結果を受け取ったりウィジェットのイベントに応答したりするアプリケーション側のコードであり、サーバー側の検証ステップそのものではありません。
• まず現在のウィジェットの data-callback 属性を確認し、ページが明示的レンダリングを使っている場合は grecaptcha.render に渡されるオプションを調べます。
• reCAPTCHA v3 では、grecaptcha.execute の結果に紐づくハンドラも確認します。すべての実装が名前付きのグローバルコールバックを公開しているとは限りません。
• コピーした内部オブジェクトパスに依存するのではなく、ブラウザのデバッグ機能を使ってアプリケーションのハンドラと送信リクエストを追跡します。
• コールバックが正常に実行されても、サーバーがトークンを受理したり、意図した処理が完了したことの証明にはなりません。

CAPTCHA の解答は取得できているのにフォームが変化しないことがあります。原因の一つとして、アプリケーション側が状態更新や次のリクエスト送信のための結果ハンドラを期待している場合が挙げられます。そのハンドラを特定すれば、何が抜けているのかを説明できますが、すべてのページが同じコールバック呼び出しを必要としているわけではありません。

CapSolver を使用する際は、「返ってきたソリューション」と「それを消費するコード」を区別してください。まずはウィジェット属性から入り、レンダリングコードを調べ、そのうえで必要に応じてアプリケーションをデバッグします。どのハンドラが関与するかは、reCAPTCHA のバージョンとページ側の統合方法に依存します。自分が所有している、または検査・自動化の許可を得ているアプリケーションにのみ使用してください。目的は既存の統合を理解することであり、汎用スクリプトがあらゆるサイトで有効な結果を送信できると決めつけることではありません。

reCAPTCHA コールバックとは何か？

reCAPTCHA コールバックとは、成功したレスポンストークンの受信など、CAPTCHA イベントに対してページが応答するために使用する関数です。

Google の reCAPTCHA v2 表示リファレンス では、成功時コールバック用の HTML 属性とレンダリングオプションが両方とも文書化されています。ページ側では、有効期限切れやエラー用のハンドラも定義しているかもしれません。これらのハンドラは目的が異なり、成功結果の経路と混同すべきではありません。

コールバックは トークン を保存したり、フォーム状態を更新したり、コントロールを有効化したり、アプリケーションのリクエストを開始したりできます。具体的に何をするかはアプリケーションによって決まります。名前だけで挙動が決まるわけではありませんし、すべてのサイトが onSuccess という関数名を使う義務もありません。

サーバー側検証は別ステップです。ブラウザ側のハンドラがエラーなく動作しても、バックエンドではレスポンスの検証とアプリケーション独自のルール適用がまだ必要です。コールバックはフローの1地点に過ぎず、完了の最終的な証拠として扱うべきではありません。

コールバックを調べる前に、現在のウィジェットを特定する

コールバックを探す前に、そのページ・フォーム・CAPTCHA バージョン・ワークフローのステップを特定します。

1 つのページに複数のウィジェットが存在することがあります。非アクティブなコンポーネントや別フォームの検索結果は、トラブルシュート中の操作とは無関係かもしれません。まず対象のステップを再現し、実際にそこで使われているウィジェットを調べてください。

開発環境と本番環境は区別可能にしておきます。ローカルビルドでは関数名が読みやすくても、本番バンドルでは難読化されているかもしれません。設定されている公開サイトキーも異なる場合があります。別環境からコールバックパスを移植するのではなく、そのページの実際のソースと実行時の挙動を使ってください。

CapSolver パラメータ検出ツール はチャレンジパラメータの特定に役立ちますが、結果を消費するハンドラの理解を置き換えるものではありません。どの CAPTCHA ファミリか分からない場合は、まず CAPTCHA 識別ガイド を使ってください。

画像パズルが出るかどうかだけでバージョンを推測しないでください。実装内容や、どの API がどのように使われているかといった情報の方が、1 枚のスクリーンショットよりはるかに確実な根拠になります。

方法1: ウィジェットのマークアップで data-callback を探す

ハンドラが HTML で宣言されている統合では、対象ウィジェットのマークアップから data-callback を検索します。

ページの開発者ツールを開き、チャレンジを含むフォームやコンポーネントを調査します。Elements パネルで、この属性名を正確に検索します。もしあれば、その名前付きハンドラと、それが紐づいているウィジェットを控えておきます。

次に、そのハンドラをアプリケーションのソースコード内で探します。トークン引数をどう扱っているかを読み解いてください。状態変数を更新しているかもしれませんし、別の関数に値を渡しているだけかもしれませんし、追加検証を通ったあとにだけフォームを送信している場合もあります。名前を見つけるのは、チェックの始まりに過ぎません。

成功・有効期限切れ・エラーのコールバックを区別する

成功経路を理解するには成功時ハンドラを使い、有効期限切れやエラー用ハンドラは別分岐として調べます。

Google の invisible reCAPTCHA リファレンス では、これらの異なるコールバックオプションが文書化されています。有効期限切れハンドラは状態のクリアや再検証の促しを行うかもしれません。エラーハンドラは接続メッセージの表示を行うかもしれません。いずれも成功時ハンドラの代わりとして扱うべきではありません。

data-callback が存在しないからといって、統合が壊れていると結論づけないでください。アプリケーションは JavaScript でコールバックを登録しているかもしれませんし、別の文書化された結果フローを使っている可能性もあります。ページに任意の属性を付け足すのではなく、レンダリングコードの方へ進みましょう。

方法2: grecaptcha.render に渡されるコールバックを調べる

ウィジェットが JavaScript で明示的に生成される場合は、grecaptcha.render に渡される設定を調べます。

読み込まれたアプリケーションソースからレンダリング呼び出しを探し、そのオプションを確認します。callback エントリは名前付き関数を指しているか、インライン関数を含んでいるかもしれません。その参照をたどってアプリケーションコードを確認し、どのフォームやコンポーネントを更新しているのかを特定します。

レンダリング呼び出し自体は、そのページが reCAPTCHA v3 を使っている証拠にはなりません。バージョンの特定には、統合全体のコンテキストを使う必要があります。コピーしてきたコード断片に付いている「v3」などのラベルだけでは、ソルバータスクや結果処理方法を選ぶ根拠として不十分です。

読み込み順とウィジェットインスタンスを確認する

見つけたコードが、本当に現在のウィジェットに対して実行されているか確認します。

初期化関数が定義されていても一度も呼ばれていない場合がありますし、依存するオブジェクトが利用可能になる前に実行される場合もあります。後から別のコンポーネントがウィジェットを置き換えていることもあります。ソース内のすべてのレンダリング呼び出しが、画面に表示されているフォームに属していると決めつけるのではなく、ブレークポイントを使って実際の経路を観察してください。

複数のウィジェットがある場合、それぞれの識別子とアプリケーション状態を区別して扱います。1 つのコンポーネントを更新するハンドラが、別ウィジェット向けの結果を黙って消費してしまうべきではありません。単独では動作するフォームが、同一アプリケーション内でのナビゲーション後に失敗する現象を診断するうえでも有用です。

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

自動化用の予算を今すぐ増やしましょう！
CapSolver アカウントにチャージする際、ボーナスコード CAP26 を使うと、チャージごとに 5% のボーナス が無制限で付与されます。
今すぐ CapSolver ダッシュボード で引き換えてください。

方法3: reCAPTCHA v3 の結果ハンドラを追跡する

reCAPTCHA v3 では、実行呼び出しの結果がアプリケーションでどのように処理されるかを調べます。

Google の reCAPTCHA v3 ガイド には、grecaptcha.execute がトークンを Promise ハンドラに返すプログラムフローが示されています。このハンドラがアプリケーションの次のアクションを含みます。ウィジェットマークアップからコピーできるグローバル関数名が存在しない場合もあります。

実行からハンドラ、そしてバックエンドリクエストまでコードをたどります。アプリケーションで使用されている action コンテキストを記録し、返された値が意図したリクエストに届いていることを確認します。同じくトークンを受け取るという理由だけで、別アクション用のハンドラを代用しないでください。

無名関数もアプリケーションハンドラである

無名関数も、安定したグローバル名で参照できないだけで、名前付きコールバックと同じ仕事を実行できます。

ソース内でその登録箇所を見つけ、デバッガで観察してください。自分のコードベースであれば、最も明快な方法はアプリケーションの明示的なハンドラインターフェースを確認・テストすることです。チュートリアルに合わせるためだけに内部関数の名前を変更したり外部公開したりすると、実装への不必要な結合を生む可能性があります。

重要なのは、トークンがどこへ行き、その後どのような状態変化が続くかという点です。関数に分かりやすい名前が付いているかどうかは、そのデータフローに比べれば二次的な問題です。

方法4: 名前が不明瞭なときはデバッグを使う

属性やソース検索でも有効なハンドラがはっきりしない場合は、ブレークポイントとコールスタックを利用します。

Chrome の ブレークポイントのドキュメント には、コード行・関数・例外ブレークポイントについて説明があります。アプリケーションハンドラ内にブレークポイントを置けば、引数・周辺状態・次の呼び出しを確認できます。例外ブレークポイントは、ハンドラ自体は動いているものの、フォーム更新前に停止してしまうケースを特定するのに役立ちます。

バンドルされたアプリケーションの場合は、利用可能なソースマップと自分が管理しているソースを使います。実装依存のランタイムオブジェクト経由のパスよりも、読みやすいソース位置の方が保守しやすいからです。関数が現在のスコープ外にある場合は、コンソールから名前で呼び出せると決めつけるのではなく、どこで登録されているかを調べてください。

自動内部オブジェクト検索に頼らない理由

内部オブジェクト検索は、文書化された統合契約の代替にはなりません。

過去のデバッグ例では、___grecaptcha_cfg.clients を調べ、ネストしたオブジェクトをたどってパスを組み立てることがありました。そうしたパスは、観測されたある実行時レイアウトを記述しているに過ぎません。ここで引用している公式の統合リファレンスでは、そのレイアウトや数値 ID、ネストされたプロパティ名がバージョンやビルドをまたいで安定しているとは約束していません。

CAPTCHA バージョンの特定や永続的な統合には、数値の内部クライアント ID やネストされたコールバックパスではなく、サポートされたウィジェット設定とアプリケーションソースを主な根拠として使ってください。このため本ガイドでは、本番用途に信頼できる自動トラバーサルスクリプトは提示していません。

コールバック実行後に何が起きるかを確認する

トークンを処理したあと、アプリケーションが意図したリクエストを送信し、そのリクエストに対してアプリケーション自身の成功結果を受け取っているかを確認します。

自分が所有するテストフォームであれば、ブラウザ側の状態遷移とバックエンドレスポンスの両方を調査してください。ハンドラは正常に動いていても、別のバリデーションルールが送信を阻害している場合があります。逆に、リクエストは送られているものの、検証中に拒否されていることもあります。これらの結果には異なる修正が必要です。

CapSolver reCAPTCHA v2 タスクリファレンス にはソルバーのレスポンスが記載されていますが、そのレスポンスがワークフローにどのように組み込まれるかはアプリケーションコードが決めます。隠しフィールドに値を代入すれば、必ずフレームワークの状態更新やフォーム送信がトリガーされると決めつけないでください。実際のアプリケーション契約を追いかけましょう。

Google の サーバー側検証リファレンス では、トークンは一度きり有効で、有効期限は 2 分であると説明されています。デバッグに時間がかかれば、その後の送信結果は変わる可能性があります。必要に応じて、許可されたフローを通じて新しいレスポンスを取得し、期限切れトークンを無関係なフォーム挙動の診断に使わないでください。

診断出力は最小限に保つ

ハンドラの位置、紐づくウィジェット、その関数が実行されたかどうか、そしてどの段階で進行が止まったかを記録します。

完全なトークンや API キー、Cookie、無関係なフォーム値を公開レポートに貼り付けるのは避けてください。「ハンドラは値を受け取り、送信は行われたが、バックエンドがレスポンスを拒否した」という程度の説明であれば、多くの場合値そのものを公開せずに済みます。サポートが追加の証拠を必要とする場合は、適切なチャネルを通じて提供してください。

結果から完了まで、アプリケーション契約をたどる

最も有用なコールバック調査とは、1 つの現在のウィジェットから、その登録ハンドラ、バックエンドリクエスト、そして最終的なアプリケーション結果までを結びつけることです。

data-callback から始め、明示的レンダリングや v3 の結果ハンドラを調べ、ソース上の経路が不明瞭な箇所ではデバッグを使ってください。CapSolver はサポートされた解決ステップを提供しますが、その結果が許可されたワークフローにどう参加するかは、アプリケーション側のハンドリングで決まります。

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

現在のチャレンジパラメータとアプリケーションの結果処理経路を検証してから、ソルブの繰り返しやワークフロー拡張を行ってください。

FAQ

Q: すべての reCAPTCHA 統合に名前付きコールバックがありますか？

いいえ。ハンドラは JavaScript から登録されたり、Promise に紐づけられたりし、無名である場合もあります。グローバル関数が存在すると決めつけず、実際の統合を調査してください。

Q: reCAPTCHA コールバックはまずどこを探せばよいですか？

対象ウィジェットの data-callback 属性から確認し、その後 grecaptcha.render に渡されるオプションと、アプリケーションの結果処理コードを調べてください。

Q: grecaptcha.render が使われていれば v3 という意味ですか？

いいえ。メソッド名だけではバージョンを特定するには不十分です。ソルバーへの入力項目やレスポンス処理を選ぶ前に、設定された統合全体を確認してください。

Q: コピーした ___grecaptcha_cfg のパスは信頼できますか？

特定の実行時環境で観測された情報として扱い、安定した公開 API とは見なさないでください。長期的に保守する統合では、文書化された設定やアプリケーションソースを優先してください。

Q: コールバックは動いているのにフォームが失敗するのはなぜですか？

コールバックはフローの一段階に過ぎません。フォームバリデーション、その結果を運ぶリクエスト、サーバー側の検証、そしてトークンが使用時点まで有効だったかを確認してください。