スコアベース キーをウェブサイトにインストールする

このページでは、スコアベースのキーをチャレンジなしでウェブサイトにインストールする方法について説明します。スコアベース キーを使用すると、ユーザーに CAPTCHA チャレンジの解決を求めることなく、サイト全体に reCAPTCHA を含めることができます。

スコアベース キーがインストールされている場合、エンドユーザーが操作をトリガーすると、reCAPTCHA は暗号化されたレスポンスである reCAPTCHA レスポンス トークン（トークン）を送信します。トークンが生成されたら、2 分以内に評価を作成して、各リクエストのスコアを受信する必要があります。このスコアに基づいて、ユーザー インタラクションのリスクレベルを把握し、適切なレスポンス（複数可）を構成できます。また、スコアベース キーは、新しい攻撃または対象にされていることを早期に警告するために bot アクティビティ テレメトリーを収集できます。

reCAPTCHA のリスクモデルを向上させるには、サイトの各ページに reCAPTCHA を含めることをおすすめします。reCAPTCHA は、実際のユーザーや bot がさまざまなページやアクション間をどのように遷移するかを理解するのに役立ちます。

始める前に

  1. reCAPTCHA 用に環境を準備します。

  2. スコアベース キーを作成します。

    あるいは、次のいずれかの手順で、既存のスコアベースのキーの ID をコピーできます。

    • Google Cloud コンソールから既存のキーの ID をコピーするには、次の操作を行います。

      1. [reCAPTCHA] ページに移動します。

        [reCAPTCHA] に移動

      2. reCAPTCHA キーのリストで、コピーするキーの上にポインタを置き、[] をクリックします。
    • REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを使用します。
    • gcloud CLI を使用して既存のキーの ID をコピーするには、gcloud recaptcha keys list コマンドを使用します。

キーをウェブサイトに配置する

reCAPTCHA は、サイト上でのインタラクションに関するコンテキストがある場合に最も効果的です。reCAPTCHA は、サイト上のインタラクションを調査するために、正当な動作と不正な動作の両方を監視します。

最適な結果を得るには、スコアベース キーをウェブサイトの次の場所にインストールします。

  • フォーム
  • アクション（ユーザー インタラクション）
  • すべてのウェブページのバックグラウンド

スコアベース キーはユーザーの作業を中断しないため、コンバージョンに影響を与えることなく、必要に応じてスコアベース キーを使用して reCAPTCHA を実行できます。

キーをフロントエンドへ統合する

検証が必要なユーザー操作に reCAPTCHA による確認を追加することをおすすめします。たとえば、フォームの送信アクションを検証する場合は、送信アクションに reCAPTCHA による確認を追加する必要があります。

reCAPTCHA による確認を追加する場所に応じて、適切なオプションを選択します。

各オプションの例は、デモウェブサイトのソースコードをご覧ください。

ユーザーの操作に関する確認を追加する

  1. ウェブページに reCAPTCHA を読み込むには、スコアベース キーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script> で指定します。サポートされている言語については、reCAPTCHA の言語コードをご覧ください。

    バッジのロケーションを指定する場合は、スクリプト タグでクエリ パラメータとして badge=LOCATION を使用します。例: www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft。デフォルトの場所は bottomright に設定されています。その他の可能な値は inline と bottomleft です。

  2. ユーザー操作に reCAPTCHA による確認を追加する手順は次のとおりです。

    1. reCAPTCHA ライブラリの読み込み時に grecaptcha.enterprise.execute() が実行されるようにするため、grecaptcha.enterprise.ready() を使用します。

    2. スコアベースのキーを使用して、保護対象のインタラクションごとに grecaptcha.enterprise.execute() を呼び出します。action パラメータで、ユーザー インタラクションに意味のある名前を指定します。詳しいガイダンスについては、アクションをご覧ください。

      次の例では、ログイン アクションで grecaptcha.enterprise.execute() を呼び出す方法を示します。

      <script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/docs/create-assessment
  });
}
</script>

      grecaptcha.enterprise.execute() によって、次の例のようにトークンが生成されます。

      03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

  3. トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

    WAF 統合でアクション トークン キーを統合する場合は、事前定義されたリクエスト ヘッダーにトークンを添付する必要があり、評価を作成する必要はありません。詳細については、reCAPTCHA アクション トークンを実装するをご覧ください。

HTML ボタンに reCAPTCHA を追加する

  1. ウェブページに reCAPTCHA を読み込むには、スコアベース キーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、<script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script> で指定します。サポートされている言語については、reCAPTCHA の言語コードをご覧ください。

  2. 単純な HTML ボタンに reCAPTCHA を追加する手順は次のとおりです。

    1. トークンを処理するコールバック関数を定義します。

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      詳細については、requestSubmit() メソッドをご覧ください。

    2. html ボタンに属性を追加します。

      <button class="g-recaptcha"
data-sitekey="KEY_ID"
data-callback="onSubmit"
data-action="submit">Submit</button>

      バッジの位置を指定する場合は、class=g-recaptcha を含む要素に data-badge=LOCATION 属性を使用します。デフォルトの場所は bottomright に設定されています。その他の可能な値は inline と bottomleft です。

    3. サイトでのフォームの送信にこのボタンを使用すると、g-recaptcha-response POST パラメータにレスポンス トークンが含まれます。

  3. トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

    WAF 統合でアクション トークン キーを統合する場合は、事前定義されたリクエスト ヘッダーにトークンを添付する必要があり、評価を作成する必要はありません。詳細については、reCAPTCHA アクション トークンを実装するをご覧ください。

次のステップ

  • reCAPTCHA の応答トークンを評価するため、評価を作成する。