在網頁中安裝通用金鑰

本文說明如何安裝通用金鑰，並與網頁整合。

事前準備

  1. 準備 reCAPTCHA 環境。

  2. 建立通用金鑰並設定網域。

在網站上安裝通用金鑰

如要安裝通用金鑰並保護網頁，請選擇 Google Cloud Fraud Defense AutoExecute 設定或標準 JavaScript 安裝方式：

AutoExecute 設定

Fraud Defense AutoExecute 可攔截網頁上的網路要求，簡化前端 JavaScript 整合程序，不必為每個前端動作手動呼叫 grecaptcha.enterprise.execute()。

  • AutoExecute 只會攔截使用 Fetch API 或 XMLHttpRequest 啟動的非同步網路要求，包括來自使用這些 API 的 AJAX 等架構的要求。
  • 系統不支援在網頁載入時自動載入的資源使用 AutoExecute。請改為對網頁上使用者動作觸發的網路要求套用 AutoExecute，例如登入按鈕。
  • 為避免 Fraud Defense 驗證導致網路逾時，請直接對要求套用逾時。請使用 AbortSignal.timeout(n) 搭配 Fetch API，並使用 XMLHttpRequest.timeout 屬性搭配 XMLHttpRequest。

在網頁中加入指令碼標記

如要在網頁上載入 reCAPTCHA，請在網頁的 <head></head> 元素中加入 JavaScript API 和通用金鑰：

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

根據預設，Fraud Defense 功能會使用瀏覽器的語言。如要指定其他語言，請在指令碼中使用 hl=LANG 屬性。舉例來說，如要使用法文，請指定下列項目：

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

如要瞭解支援的語言，請參閱「Fraud Defense 適用的語言代碼」。

設定受保護的端點

Fraud Defense 指令碼會自動與通用金鑰政策設定中定義的網路動作整合。這個部分會定義網址路徑 (path) 對應至動作名稱 (action)。

如果 Fraud Defense 指令碼偵測到對應路徑的非同步網路要求，就會攔截該要求、觸發風險評估，並在原始要求繼續執行前，向使用者顯示 CAPTCHA 驗證。產生的回應權杖會自動附加至要求中的 X-Recaptcha-Token 標頭。

gcloud

如要檢查通用金鑰的目前政策設定，請使用 gcloud alpha recaptcha policies describe 指令：

gcloud alpha recaptcha policies describe --key=KEY_ID

如要使用受保護的端點更新政策設定，請建立 YAML 檔案 (例如 POLICY.yaml)，定義受保護的路徑和動作：

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

使用 gcloud alpha recaptcha policies update 指令，透過 YAML 檔案更新金鑰設定：

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

REST API

如要使用 REST API 更新政策設定，定義受保護的端點，請使用 projects.keys.updatePolicy 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • KEY_ID：通用金鑰的 ID

HTTP 方法和網址：

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

JSON 要求主體：

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

請展開以下其中一個選項，以傳送要求：

如果要求成功，系統會傳回更新後的政策設定。

path 參數支援符合下列規則的 glob 模式：

  • 開頭須為 /，且不得留空。
  • 不得為獨立的 /* 或 /**，因為如果每次向後端發出的請求都觸發詐欺防護機制，可能會對效能造成負面影響。
  • 萬用字元 * (符合單一路徑片段) 和 ** (符合多個路徑片段) 必須佔據整個路徑片段 (例如 /api/*/login 或 /api/* 為有效；/api/login* 為無效)。
  • ** 萬用字元只能佔用最後一個路徑片段 (例如 /api/** 有效，/api/**/login 無效)。
  • 第三方要求：如果網頁上執行的第三方工具 (例如數據分析或合作夥伴指令碼) 向與受保護端點相符的路徑傳送要求 (例如https://analytics.example.net/login相符/login)，AutoExecute也會攔截這些要求。這可能會導致額外的網路延遲、指標偏斜或出現非預期的 CAPTCHA 驗證。為避免衝突，請確保受保護的路徑獨一無二 (例如 /auth/v1/login)，或在發生路徑衝突時使用標準安裝。
  • 跨網域 API：如果後端 API 託管在與網站不同的網域 (例如 examplecdn.net 與 www.example.com)，AutoExecute 會自動運作，不需要額外的網域設定。

如果您的整合服務需要比對特定目的地網域，請提出功能要求。

在後端，從 X-Recaptcha-Token 要求標頭取得回應權杖，並在兩分鐘內建立評估。

標準安裝

建議您在需要驗證的使用者互動中新增 Fraud Defense 驗證。舉例來說，如要驗證表單的提交動作，您需要在提交動作中新增 Fraud Defense 驗證。

視要新增 Fraud Defense 驗證的位置而定，選擇適當的選項：

在使用者互動時新增驗證

  1. 如要在網頁上載入 reCAPTCHA，請在網頁的 <head></head> 元素中加入 JavaScript API 和通用金鑰：

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

    Fraud Defense 根據預設會使用瀏覽器的語言。如要指定其他語言，請在指令碼中使用 hl=LANG 屬性。舉例來說，如要使用法文，請指定下列項目：

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

    如要瞭解支援的語言，請參閱「Fraud Defense 適用的語言代碼」。

    如要指定徽章位置，請在指令碼標記中使用 badge=LOCATION 做為查詢參數。例如：https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft。根據預設，位置會設為 bottomright。其他可能的值為 inline 和 bottomleft。

  2. 如要在使用者互動中新增 Fraud Defense 驗證，請按照下列步驟操作：

    1. 為確保 grecaptcha.enterprise.execute() 在載入 Fraud Defense 程式庫後執行，請使用 grecaptcha.enterprise.ready()。

    2. 針對要使用通用金鑰保護的每次互動呼叫 grecaptcha.enterprise.execute()。在 action 參數中，為使用者互動指定有意義的名稱。如需更多指引，請參閱「動作」。

      以下範例說明如何對登入動作呼叫 grecaptcha.enterprise.execute()：

      <script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  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 Fraud Defense 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>

      秒

  3. 系統產生權杖後，請將 reCAPTCHA 權杖傳送至後端，並在兩分鐘內建立評估。

在 HTML 按鈕上新增 Fraud Defense

  1. 如要在網頁上載入 reCAPTCHA，請在網頁的 <head></head> 元素中，加入含有通用金鑰的 JavaScript API：

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

    Fraud Defense 根據預設會使用瀏覽器的語言。如要指定其他語言，請在指令碼中使用 hl=LANG 屬性。舉例來說，如要使用法文，請指定下列項目：

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

    如要瞭解支援的語言，請參閱「Fraud Defense 適用的語言代碼」。

  2. 如要在 HTML 按鈕上新增 Fraud Defense，請按照下列步驟操作：

    1. 指定用來處理權杖的回呼函式。
    <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

    詳情請參閱 requestSubmit() 方法。

    1. 為 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。

    1. 如果有人使用這個按鈕提交網站上的表單，g-recaptcha-response POST 參數就會包含回應權杖。

  3. 系統產生權杖後，請將 reCAPTCHA 權杖傳送至後端，並在兩分鐘內建立評估。

後續步驟