**推出 的新主控台體驗 AWS WAF**

您現在可以使用更新後的體驗，在主控台的任何位置存取 AWS WAF 功能。如需詳細資訊，請參閱[使用 主控台](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 中的用戶端應用程式整合 AWS WAF
<a name="waf-application-integration"></a>

本節說明如何將智慧型威脅整合 APIs和 JavaScript CAPTCHA 整合 API 與您的 AWS WAF 功能搭配使用。

使用 AWS WAF 用戶端應用程式整合 APIs 將用戶端保護與您的 AWS 伺服器端保護套件 (Web ACL) 保護耦合，以協助驗證將 Web 請求傳送至受保護資源的用戶端應用程式是否為預期的用戶端，以及您的最終使用者是否為人類。

使用用戶端整合來管理無提示的瀏覽器挑戰和 CAPTCHA 拼圖、取得具有成功瀏覽器和最終使用者回應證明的字符，以及將這些字符包含在對受保護端點的請求中。如需 AWS WAF 字符的一般資訊，請參閱 [用於 AWS WAF 智慧型威脅緩解的字符](waf-tokens.md)。

將用戶端整合與需要有效字符才能存取 資源的保護套件 (Web ACL) 保護結合。您可以使用規則群組來檢查和監控挑戰字符，例如下一節列出的挑戰字符，網址為 [智慧威脅整合和 AWS 受管規則](waf-application-integration-with-AMRs.md)，而且您可以使用 CAPTCHA和 Challenge規則動作來檢查，如 中所述[CAPTCHA 和 Challenge 中的 AWS WAF](waf-captcha-and-challenge.md)。

AWS WAF 為 JavaScript 應用程式提供兩種整合層級，並為行動應用程式提供一種：
+ **智慧威脅整合** – 驗證用戶端應用程式，並提供 AWS 權杖取得和管理。這類似於規則動作所提供的 AWS WAF Challenge功能。此功能完全整合您的用戶端應用程式與`AWSManagedRulesACFPRuleSet`受管規則群組、`AWSManagedRulesATPRuleSet`受管規則群組，以及`AWSManagedRulesBotControlRuleSet`受管規則群組的目標保護層級。

  智慧型威脅整合 APIs 使用無 AWS WAF 提示瀏覽器挑戰，以協助確保只有在用戶端取得有效的字符之後，才允許對您受保護資源的登入嘗試和其他呼叫。APIs 會管理用戶端應用程式工作階段的字符授權，並收集用戶端的相關資訊，以協助判斷其是否由機器人或人類操作。
**注意**  
這適用於 JavaScript 和 Android 和 iOS 行動應用程式。
+ **CAPTCHA 整合** – 使用您在應用程式中管理的自訂 CAPTCHA 拼圖來驗證最終使用者。這類似於規則動作所提供的 AWS WAF CAPTCHA功能，但增加了對拼圖放置和行為的控制。

  此整合利用 JavaScript 智慧型威脅整合來執行無聲挑戰，並將 AWS WAF 權杖提供給客戶的頁面。
**注意**  
這適用於 JavaScript 應用程式。

**Topics**
+ [智慧威脅整合和 AWS 受管規則](waf-application-integration-with-AMRs.md)
+ [存取 AWS WAF 用戶端應用程式整合 APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript 整合](waf-javascript-api.md)
+ [AWS WAF 行動應用程式整合](waf-mobile-sdk.md)

# 智慧威脅整合和 AWS 受管規則
<a name="waf-application-integration-with-AMRs"></a>

本節說明智慧型威脅整合 APIs如何與 AWS 受管規則規則群組搭配使用。

智慧型威脅整合 APIs 可與使用智慧型威脅規則群組的保護套件 (Web ACLs) 搭配使用，以啟用這些進階受管規則群組的完整功能。
+ AWS WAF 詐騙控制帳戶建立詐騙預防 (ACFP) 受管規則群組 `AWSManagedRulesACFPRuleSet`。

  帳戶建立詐騙是一種線上非法活動，攻擊者會在您的應用程式中建立無效的帳戶，例如接收註冊獎金或冒充某人。ACFP 受管規則群組提供規則來封鎖、標記和管理可能屬於詐騙帳戶建立嘗試一部分的請求。APIs 可啟用經過微調的用戶端瀏覽器驗證和人類互動資訊，以供 ACFP 規則用來區隔有效的用戶端流量與惡意流量。

  如需詳細資訊，請參閱[AWS WAF 詐騙控制帳戶建立詐騙預防 (ACFP) 規則群組](aws-managed-rule-groups-acfp.md)及[AWS WAF 詐騙控制帳戶建立詐騙預防 (ACFP)](waf-acfp.md)。
+ AWS WAF 詐騙控制帳戶接管預防 (ATP) 受管規則群組 `AWSManagedRulesATPRuleSet`。

  帳戶接管是一種線上非法活動，攻擊者可在其中未經授權存取某人的帳戶。ATP 受管規則群組提供規則來封鎖、標記和管理可能屬於惡意帳戶接管嘗試一部分的請求。APIs 可啟用微調的用戶端驗證和行為彙總，讓 ATP 規則用來區隔有效的用戶端流量與惡意流量。

  如需詳細資訊，請參閱[AWS WAF 詐騙控制帳戶接管預防 (ATP) 規則群組](aws-managed-rule-groups-atp.md)及[AWS WAF 詐騙控制帳戶接管預防 (ATP)](waf-atp.md)。
+  AWS WAF Bot Control 受管規則群組 的目標保護層級`AWSManagedRulesBotControlRuleSet`。

  機器人從自我識別和有用的機器人執行，例如大多數搜尋引擎和爬蟲程式，到針對您的網站操作且不自我識別的惡意機器人。Bot Control 受管規則群組提供規則來監控、標記和管理 Web 流量中的機器人活動。當您使用此規則群組的目標保護層級時，目標規則會使用 APIs提供的用戶端工作階段資訊，以更有效偵測惡意機器人。

  如需詳細資訊，請參閱[AWS WAF 機器人控制規則群組](aws-managed-rule-groups-bot.md)及[AWS WAF 機器人控制](waf-bot-control.md)。

若要將其中一個受管規則群組新增至保護套件 (Web ACL)[將 ATP 受管規則群組新增至保護套件 (Web ACL)](waf-atp-rg-using.md)，請參閱程序 [將 ACFP 受管規則群組新增至 Web ACL](waf-acfp-rg-using.md)、 和 [將 AWS WAF Bot Control 受管規則群組新增至 Web ACL](waf-bot-control-rg-using.md)。

**注意**  
受管規則群組目前不會封鎖缺少字符的請求。為了封鎖缺少權杖的請求，在您實作應用程式整合 APIs 之後，請遵循 中的指引[封鎖沒有有效 AWS WAF 字符的請求](waf-tokens-block-missing-tokens.md)。

# 存取 AWS WAF 用戶端應用程式整合 APIs
<a name="waf-application-integration-location-in-console"></a>

本節說明在 AWS WAF 主控台中尋找應用程式整合 APIs的位置。

JavaScript 整合 APIs已全面推出，您可以將其用於您的瀏覽器和其他執行 JavaScript 的裝置。

AWS WAF 提供適用於 Android 和 iOS 行動應用程式的自訂智慧型威脅整合 SDKs。
+ 對於 Android 行動和電視應用程式，SDKs適用於 Android API 第 23 版 (Android 第 6 版） 和更新版本。如需 Android 版本的資訊，請參閱 [SDK 平台版本備註](https://developer.android.com/tools/releases/platforms)。
+ 對於 iOS 行動應用程式，SDKs適用於 iOS 版本 13 和更新版本。如需 iOS 版本的資訊，請參閱 [iOS & iPadOS 版本備註](https://developer.apple.com/documentation/ios-ipados-release-notes)。
+ 對於 Apple TV 應用程式，SDKs適用於 tvOS 第 14 版或更新版本。如需 tvOS 版本的資訊，請參閱 [tvOS 版本備註](https://developer.apple.com/documentation/tvos-release-notes)。

**透過主控台存取整合 APIs**

1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。

1. 在導覽窗格中選擇**應用程式整合**，然後選擇您感興趣的索引標籤。
   + **智慧型威脅整合**適用於 JavaScript 和行動應用程式。

     標籤包含下列項目：
     + 已啟用智慧型威脅應用程式整合的保護套件 (Web ACLs) 清單。此清單包含每個使用`AWSManagedRulesACFPRuleSet`受管規則群組、`AWSManagedRulesATPRuleSet`受管規則群組或`AWSManagedRulesBotControlRuleSet`受管規則群組的目標保護層級的保護套件 (Web ACL)。當您實作智慧型威脅 APIs 時，您可以使用要與之整合的保護套件 (Web ACL) 的整合 URL。
     + 您可以存取APIs。JavaScript APIs 一律可用。如需存取行動SDKs，請聯絡 [Contact AWS](https://aws.amazon.com/contact-us) 的支援。
   + **CAPTCHA 整合**適用於 JavaScript 應用程式。

     標籤包含下列項目：
     + 用於整合的整合 URL。
     + 您為用戶端應用程式網域建立的 API 金鑰。您使用 CAPTCHA API 需要加密的 API 金鑰，讓用戶端有權從其網域存取 AWS WAF CAPTCHA。對於您整合的每個用戶端，請使用包含用戶端網域的 API 金鑰。如需這些要求以及管理這些金鑰的詳細資訊，請參閱 [管理 JS CAPTCHA API 的 API 金鑰](waf-js-captcha-api-key.md)。

# AWS WAF JavaScript 整合
<a name="waf-javascript-api"></a>

本節說明如何使用 AWS WAF JavaScript 整合。

您可以使用 JavaScript 整合 APIs 在瀏覽器和其他執行 JavaScript 的裝置中實作 AWS WAF 應用程式整合。

CAPTCHA 拼圖和無提示挑戰只能在瀏覽器存取 HTTPS 端點時執行。瀏覽器用戶端必須在安全的內容中執行，才能取得字符。
+ 智慧型威脅 APIs 可讓您透過無提示的用戶端瀏覽器挑戰來管理權杖授權，並在您傳送至受保護資源的請求中包含權杖。
+ CAPTCHA 整合 API 會新增至智慧型威脅 APIs，並可讓您自訂用戶端應用程式中 CAPTCHA 拼圖的位置和特性。此 API 利用智慧型威脅 APIs 來取得 AWS WAF 權杖，以便在最終使用者成功完成 CAPTCHA 拼圖後，用於 頁面。

透過使用這些整合，您可以確保用戶端的遠端程序呼叫包含有效的字符。當您的應用程式頁面上有這些整合 APIs 時，您可以在保護套件 (Web ACL) 中實作緩解規則，例如封鎖不包含有效字符的請求。您也可以在規則中使用 Challenge或 CAPTCHA動作，實作規則來強制使用用戶端應用程式取得的字符。

**實作智慧型威脅 APIs的範例**  
下列清單顯示 Web 應用程式頁面中智慧威脅 APIs典型實作的基本元件。

```
<head>
<script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js" defer></script>
</head>
<script>
const login_response = await AwsWafIntegration.fetch(login_url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: login_body
  });
</script>
```

**CAPTCHA JavaScript API 的範例實作**  
CAPTCHA 整合 API 可讓您自訂最終使用者的 CAPTCHA 拼圖體驗。CAPTCHA 整合利用 JavaScript 智慧型威脅整合進行瀏覽器驗證和權杖管理，並新增用於設定和轉譯 CAPTCHA 拼圖的函數。

下列清單顯示 CAPTCHA JavaScript API 在 Web 應用程式頁面中典型實作的基本元件。

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            ...
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Topics**
+ [提供用於字符的網域](waf-js-challenge-api-set-token-domain.md)
+ [搭配內容安全政策使用 JavaScript API](waf-javascript-api-csp.md)
+ [使用智慧型威脅 JavaScript API](waf-js-challenge-api.md)
+ [使用 CAPTCHA JavaScript API](waf-js-captcha-api.md)

# 提供用於字符的網域
<a name="waf-js-challenge-api-set-token-domain"></a>

本節說明如何提供字符的其他網域。

根據預設，當 AWS WAF 建立權杖時，它會使用與保護套件 (Web ACL) 相關聯的 資源的主機網域。您可以為為為 JavaScript APIs AWS WAF 建立的字符提供額外的網域。若要這樣做，`window.awsWafCookieDomainList`請使用一或多個字符網域來設定全域變數 。

當 AWS WAF 建立字符時，它會使用來自 中網域組合中最適當、最短的網域，`window.awsWafCookieDomainList`以及與保護套件相關聯的資源主機網域 (Web ACL)。

範例設定：

```
window.awsWafCookieDomainList = ['.aws.amazon.com']
```

```
window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com']
```

您無法在此清單中使用公有字尾。例如，您無法使用 `gov.au`或 `co.uk`做為清單中的字符網域。

您在此清單中指定的網域必須與其他網域和網域組態相容：
+ 根據受保護的主機網域和為保護套件設定的字符網域清單 (Web ACL)，網域必須是 AWS WAF 將接受的網域。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。
+ 如果您使用 JavaScript CAPTCHA API，CAPTCHA API 金鑰中至少有一個網域必須與 中的其中一個字符網域完全相符，`window.awsWafCookieDomainList`或者必須是其中一個字符網域的頂點網域。

  例如，對於字符網域 `mySubdomain.myApex.com`，API 金鑰`mySubdomain.myApex.com`是完全相符的，API 金鑰`myApex.com`是頂點網域。任一金鑰都符合字符網域。

  如需 API 金鑰的詳細資訊，請參閱 [管理 JS CAPTCHA API 的 API 金鑰](waf-js-captcha-api-key.md)。

如果您使用 `AWSManagedRulesACFPRuleSet`受管規則群組，您可以設定符合您提供給規則群組組態之帳戶建立路徑的網域。如需此組態的詳細資訊，請參閱「[將 ACFP 受管規則群組新增至 Web ACL](waf-acfp-rg-using.md)」。

如果您使用 `AWSManagedRulesATPRuleSet`受管規則群組，您可以在您提供給規則群組組態的登入路徑中，設定符合該網域的網域。如需此組態的詳細資訊，請參閱「[將 ATP 受管規則群組新增至保護套件 (Web ACL)](waf-atp-rg-using.md)」。

# 搭配內容安全政策使用 JavaScript API
<a name="waf-javascript-api-csp"></a>

本節提供允許列出頂 AWS WAF 點網域的範例組態。

如果您將內容安全政策 (CSP) 套用至資源，為了讓 JavaScript AWS WAF 實作運作，您需要允許列出頂點網域 `awswaf.com`。JavaScript SDKs會呼叫不同的 AWS WAF 端點，因此允許列出此網域可提供SDKs操作所需的許可。

以下顯示允許列出 apex AWS WAF 網域的範例組態：

```
connect-src 'self' https://*.awswaf.com;
script-src 'self' https://*.awswaf.com;
script-src-elem 'self' https://*.awswaf.com;
```

如果您嘗試將 JavaScript SDKs與使用 CSP 的資源搭配使用，而且您尚未允許列出 AWS WAF 網域，您將會收到如下的錯誤：

```
Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’
```

# 使用智慧型威脅 JavaScript API
<a name="waf-js-challenge-api"></a>

本節提供在用戶端應用程式中使用智慧型威脅 JavaScript API 的指示。

智慧型威脅 APIs 提供對使用者瀏覽器執行無提示挑戰的操作，以及處理提供成功挑戰證明和 CAPTCHA 回應的 AWS WAF 字符的操作。

先在測試環境中實作 JavaScript 整合，然後在生產環境中實作。如需其他編碼指引，請參閱以下各節。

 

**使用智慧型威脅 APIs**

1. **安裝 APIs** 

   如果您使用 CAPTCHA API，則可以略過此步驟。當您安裝 CAPTCHA API 時，指令碼會自動安裝智慧型威脅 APIs。

   1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。

   1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。在**應用程式整合**頁面上，您可以看到標籤選項。

   1. 選取**智慧型威脅整合**

   1. 在 索引標籤中，選取您要整合的保護套件 (Web ACL)。保護套件 (Web ACL) 清單僅包含使用`AWSManagedRulesACFPRuleSet`受管規則群組、`AWSManagedRulesATPRuleSet`受管規則群組或`AWSManagedRulesBotControlRuleSet`受管規則群組的目標保護層級的保護套件 (Web ACLs)。

   1. 開啟 **JavaScript SDK** 窗格，並複製指令碼標籤以用於整合。

   1. 在應用程式頁面程式碼的 `<head>`區段中，插入您為保護套件複製的指令碼標籤 (Web ACL)。此包含項目會導致您的用戶端應用程式在頁面載入的背景中自動擷取字符。

      ```
      <head>
          <script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js” defer></script>
      <head>
      ```

      此`<script>`清單使用 `defer` 屬性設定，但如果`async`您想要為頁面採取不同的行為，您可以將設定變更為 。

1. **（選用） 新增用戶端字符的網域組態** – 在預設情況下，當 AWS WAF 建立字符時，它會使用與保護套件相關聯的資源的主機網域 (Web ACL)。若要提供 JavaScript APIs 的其他網域，請遵循 中的指引[提供用於字符的網域](waf-js-challenge-api-set-token-domain.md)。

1. **為您的智慧型威脅整合編寫程式碼** – 撰寫程式碼，以確保字符擷取在用戶端將其請求傳送至受保護的端點之前完成。如果您已經使用 `fetch` API 進行呼叫，則可以取代整合`fetch`包裝函式 AWS WAF 。如果您不使用 `fetch` API，則可以改用 AWS WAF 整合`getToken`操作。如需編碼指引，請參閱下列各節。

1. 在**保護套件 (Web ACL) 中新增權杖驗證** – 將至少一個規則新增至保護套件 (Web ACL)，以檢查用戶端傳送的 Web 請求中是否有有效的挑戰權杖。您可以使用規則群組來檢查和監控挑戰字符，例如 Bot Control 受管規則群組的目標層級，而且您可以使用Challenge規則動作來檢查，如中所述[CAPTCHA 和 Challenge 中的 AWS WAF](waf-captcha-and-challenge.md)。

   保護套件 (Web ACL) 新增項目會驗證對受保護端點的請求是否包含您在用戶端整合中取得的字符。包含有效、未過期字符的請求會通過Challenge檢查，並且不會向您的用戶端傳送另一個無提示挑戰。

1. **（選用） 封鎖缺少權杖的請求** – 如果您使用 APIs搭配 ACFP 受管規則群組、ATP 受管規則群組或 Bot Control 規則群組的目標規則，這些規則不會封鎖缺少權杖的請求。若要封鎖缺少字符的請求，請遵循 中的指引[封鎖沒有有效 AWS WAF 字符的請求](waf-tokens-block-missing-tokens.md)。

**Topics**
+ [智慧型威脅 API 規格](waf-js-challenge-api-specification.md)
+ [如何使用整合`fetch`包裝函式](waf-js-challenge-api-fetch-wrapper.md)
+ [如何使用整合 `getToken`](waf-js-challenge-api-get-token.md)

# 智慧型威脅 API 規格
<a name="waf-js-challenge-api-specification"></a>

本節列出智慧型威脅緩解 JavaScript APIs 的方法和屬性規格。使用這些 APIs進行智慧威脅和 CAPTCHA 整合。

**`AwsWafIntegration.fetch()`**  
使用 AWS WAF 整合實作將 HTTP `fetch`請求傳送至伺服器。

**`AwsWafIntegration.getToken()`**  
擷取存放的 AWS WAF 字符，並將其存放在目前頁面上名為 `aws-waf-token`且值設定為字符值的 Cookie 中。

**`AwsWafIntegration.hasToken()`**  
傳回布林值，指出 `aws-waf-token` Cookie 目前是否保留未過期的字符。

如果您也使用 CAPTCHA 整合，請參閱 中該整合的規格[CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)。

# 如何使用整合`fetch`包裝函式
<a name="waf-js-challenge-api-fetch-wrapper"></a>

本節提供使用整合`fetch`包裝函式的說明。

您可以在 `AwsWafIntegration` 命名空間下變更對 `fetch` API 的正常`fetch`呼叫，以使用 AWS WAF `fetch`包裝函式。 AWS WAF 包裝函式支援所有與標準 JavaScript `fetch` API 呼叫相同的選項，並新增整合的字符處理。此方法通常是整合您應用程式最簡單的方法。

**在包裝函式實作之前**  
下列範例清單顯示實作`AwsWafIntegration``fetch`包裝函式之前的標準程式碼。

```
const login_response = await fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

**包裝函式實作之後**  
以下清單顯示與`AwsWafIntegration``fetch`包裝函式實作相同的程式碼。

```
const login_response = await AwsWafIntegration.fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

# 如何使用整合 `getToken`
<a name="waf-js-challenge-api-get-token"></a>

本節說明如何使用 `getToken`操作。

AWS WAF 需要您對受保護端點的請求，以包含名為 的 Cookie `aws-waf-token`與目前字符的值。

`getToken` 操作是一種非同步 API 呼叫，會擷取 AWS WAF 字符並將其存放在目前頁面上名為 `aws-waf-token`且值設定為字符值的 Cookie 中。您可以在頁面中視需要使用此字符 Cookie。

當您呼叫 時`getToken`，它會執行下列動作：
+ 如果已可使用未過期的字符，呼叫會立即傳回它。
+ 否則，呼叫會從權杖提供者擷取新的權杖，在逾時之前等待最多 2 秒讓權杖擷取工作流程完成。如果操作逾時，它會擲回呼叫程式碼必須處理的錯誤。

`getToken` 操作具有隨附的`hasToken`操作，指出 `aws-waf-token` Cookie 目前是否擁有未過期的字符。

`AwsWafIntegration.getToken()` 會擷取有效的權杖，並將其儲存為 Cookie。大多數用戶端呼叫會自動連接此 Cookie，但有些則不會。例如，跨主機網域進行的呼叫不會連接 Cookie。在接下來的實作詳細資訊中，我們會示範如何使用這兩種類型的用戶端呼叫。

**基本`getToken`實作，適用於連接 `aws-waf-token` Cookie 的呼叫**  
下列範例清單顯示使用登入請求實作 `getToken`操作的標準程式碼。

```
const login_response = await AwsWafIntegration.getToken()
	    .catch(e => {
	        // Implement error handling logic for your use case
	    })
	    // The getToken call returns the token, and doesn't typically require special handling
	    .then(token => {
	        return loginToMyPage()
	    })
	
	async function loginToMyPage() {
	    // Your existing login code
	}
```

**僅在字符可從 取得之後才提交表單 `getToken`**  
下列清單顯示如何在有效的權杖可供使用之前，註冊事件接聽程式以攔截表單提交。

```
<body>
	  <h1>Login</h1>
	  <p></p>
	  <form id="login-form" action="/web/login" method="POST" enctype="application/x-www-form-urlencoded">
	    <label for="input_username">USERNAME</label>
	    <input type="text" name="input_username" id="input_username"><br>
	    <label for="input_password">PASSWORD</label>
	    <input type="password" name="input_password" id="input_password"><br>
	    <button type="submit">Submit<button>
	  </form>
	
	<script>
	  const form = document.querySelector("#login-form");
	
	  // Register an event listener to intercept form submissions
	  form.addEventListener("submit", (e) => {
	      // Submit the form only after a token is available 
	      if (!AwsWafIntegration.hasToken()) {
	          e.preventDefault();
	          AwsWafIntegration.getToken().then(() => {
	              e.target.submit();
	          }, (reason) => { console.log("Error:"+reason) });
	        }
	    });
	</script>
	</body>
```

**在用戶端預設不連接 `aws-waf-token` Cookie 時連接字符**  
`AwsWafIntegration.getToken()` 會擷取有效的字符並將其儲存為 Cookie，但並非所有用戶端呼叫預設會連接此 Cookie。例如，跨主機網域進行的呼叫不會連接 Cookie。

`fetch` 包裝函式會自動處理這些案例，但如果您無法使用`fetch`包裝函式，除了從 `aws-waf-token` Cookie 讀取權杖之外，您還可以使用自訂 `x-aws-waf-token` header. AWS WAF reads 權杖來處理。下列程式碼顯示設定 標頭的範例。

```
const token = await AwsWafIntegration.getToken();
const result = await fetch('/url', {
    headers: {
        'x-aws-waf-token': token,
    },
});
```

根據預設， AWS WAF 僅接受與請求的主機網域包含相同網域的權杖。任何跨網域字符都需要保護套件 (Web ACL) 字符網域清單中的對應項目。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。

如需跨網域字符使用的其他資訊，請參閱 [aws-samples/aws-waf-bot-control-api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha)。

# 使用 CAPTCHA JavaScript API
<a name="waf-js-captcha-api"></a>

本節提供使用 CAPTCHA 整合 API 的說明。

CAPTCHA JavaScript API 可讓您設定 CAPTCHA 拼圖，並將其放置在用戶端應用程式中您想要的位置。此 API 利用智慧型威脅 JavaScript APIs的功能，在最終使用者成功完成 CAPTCHA 拼圖後取得並使用 AWS WAF 字符。

先在測試環境中實作 JavaScript 整合，然後在生產環境中實作。如需其他編碼指引，請參閱以下各節。

**使用 CAPTCHA 整合 API**

1. **安裝 API**

   1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。

   1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。在**應用程式整合**頁面上，您可以看到標籤選項。

   1. 選取 **CAPTCHA 整合**。

   1. 複製列出的 JavaScript 整合指令碼標籤，以用於您的整合。

   1. 在應用程式頁面程式碼的 `<head>`區段中，插入您複製的指令碼標籤。此包含項目可讓 CAPTCHA 拼圖可供組態和使用。

      ```
      <head>
          <script type="text/javascript" src="integrationURL/jsapi.js" defer></script>
      </head>
      ```

      此`<script>`清單使用 `defer` 屬性設定，但如果`async`您想要為頁面採取不同的行為，您可以將設定變更為 。

      如果智慧型威脅整合指令碼尚未存在，CAPTCHA 指令碼也會自動載入。智慧型威脅整合指令碼可讓您的用戶端應用程式在頁面載入的背景中自動擷取字符，並提供您使用 CAPTCHA API 所需的其他字符管理功能。

1. **（選用） 新增用戶端字符的網域組態** – 在預設情況下，當 AWS WAF 建立字符時，它會使用與保護套件相關聯的資源的主機網域 (Web ACL)。若要提供 JavaScript APIs 的其他網域，請遵循 中的指引[提供用於字符的網域](waf-js-challenge-api-set-token-domain.md)。

1. **取得用戶端的加密 API 金鑰** – CAPTCHA API 需要加密的 API 金鑰，其中包含有效的用戶端網域清單。 AWS WAF 使用此金鑰來驗證您搭配整合使用的用戶端網域是否已核准使用 AWS WAF CAPTCHA。若要產生您的 API 金鑰，請遵循 中的指引[管理 JS CAPTCHA API 的 API 金鑰](waf-js-captcha-api-key.md)。

1. **為您的 CAPTCHA 小工具實作編寫程式碼**：在您的頁面中您想要使用它的位置實作 `renderCaptcha()` API 呼叫。如需有關設定和使用此函數的資訊，請參閱下列各節 [CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)和 [如何轉譯 CAPTCHA 拼圖](waf-js-captcha-api-render.md)。

   CAPTCHA 實作會與智慧威脅整合 APIs整合，以進行權杖管理，並執行使用權 AWS WAF 杖的擷取呼叫。如需使用這些 APIs的指引，請參閱 [使用智慧型威脅 JavaScript API](waf-js-challenge-api.md)。

1. 在**保護套件 (Web ACL) 中新增權杖驗證** – 將至少一個規則新增至保護套件 (Web ACL)，以檢查用戶端傳送的 Web 請求中是否有有效的 CAPTCHA 權杖。您可以使用CAPTCHA規則動作來檢查，如中所述[CAPTCHA 和 Challenge 中的 AWS WAF](waf-captcha-and-challenge.md)。

   保護套件 (Web ACL) 新增項目會驗證傳送至受保護端點的請求是否包含您在用戶端整合中取得的字符。包含有效、未過期 CAPTCHA 字符的請求會通過CAPTCHA規則動作檢查，而不會向最終使用者顯示另一個 CAPTCHA 拼圖。

實作 JavaScript API 之後，您可以檢閱 CAPTCHA 拼圖嘗試和解決方案的 CloudWatch 指標。如需指標和維度詳細資訊，請參閱 [帳戶指標和維度](waf-metrics.md#waf-metrics-account)。

**Topics**
+ [CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)
+ [如何轉譯 CAPTCHA 拼圖](waf-js-captcha-api-render.md)
+ [從 處理 CAPTCHA 回應 AWS WAF](waf-js-captcha-api-conditional.md)
+ [管理 JS CAPTCHA API 的 API 金鑰](waf-js-captcha-api-key.md)

# CAPTCHA JavaScript API 規格
<a name="waf-js-captcha-api-specification"></a>

本節列出 CAPTCHA JavaScript APIs 的方法和屬性規格。使用 CAPTCHA JavaScript APIs 在用戶端應用程式中執行自訂 CAPTCHA 拼圖。

此 API 建置在智慧型威脅 APIs上，您可用來設定和管理 AWS WAF 權杖的取得和使用。請參閱 [智慧型威脅 API 規格](waf-js-challenge-api-specification.md)。

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
向最終使用者顯示 AWS WAF CAPTCHA 拼圖，並在成功時以 CAPTCHA 驗證更新用戶端字符。這僅適用於 CAPTCHA 整合。使用此呼叫搭配智慧型威脅 APIs 來管理權杖擷取，並在您的`fetch`呼叫中提供權杖。請參閱 的智慧型威脅 APIs[智慧型威脅 API 規格](waf-js-challenge-api-specification.md)。  
與 AWS WAF 傳送的 CAPTCHA 間質不同，此方法轉譯的 CAPTCHA 拼圖會立即顯示拼圖，無需初始標題畫面。    
**`container`**  
頁面上目標容器元素的`Element`物件。這通常透過呼叫 `document.getElementById()`或 來擷取`document.querySelector()`。  
必要：是  
類型：`Element`  
**組態**  
包含 CAPTCHA 組態設定的物件，如下所示****：    
**`apiKey`**   
啟用用戶端網域許可的加密 API 金鑰。使用 AWS WAF 主控台為您的用戶端網域產生 API 金鑰。您最多可以將一個金鑰用於五個網域。如需相關資訊，請參閱[管理 JS CAPTCHA API 的 API 金鑰](waf-js-captcha-api-key.md)。  
必要：是  
類型：`string`  
**`onSuccess: (wafToken: string) => void;`**   
當最終使用者成功完成 CAPTCHA 拼圖時，使用有效的 AWS WAF 字符呼叫。在您傳送到使用 AWS WAF 保護套件 (Web ACL) 保護之端點的請求中使用字符。字符提供最新成功拼圖完成的證明和時間戳記。  
必要：是  
**`onError?: (error: CaptchaError) => void;`**   
在 CAPTCHA 操作期間發生錯誤時呼叫錯誤物件。  
必要：否  
**`CaptchaError` 類別定義** – `onError`處理常式提供具有下列類別定義的錯誤類型。  

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind` – 傳回的錯誤類型。
+ `statusCode` – HTTP 狀態碼，如果有的話。`network_error` 如果錯誤是由於 HTTP 錯誤所造成，則 會使用此功能。  
**`onLoad?: () => void;`**   
載入新的 CAPTCHA 拼圖時呼叫。  
必要：否  
**`onPuzzleTimeout?: () => void;`**   
在 CAPTCHA 拼圖過期之前未完成時呼叫。  
必要：否  
**`onPuzzleCorrect?: () => void;`**   
將正確答案提供給 CAPTCHA 拼圖時呼叫。  
必要：否  
**`onPuzzleIncorrect?: () => void;`**   
當向 CAPTCHA 拼圖提供不正確的答案時呼叫。  
必要：否  
**`defaultLocale`**   
用於 CAPTCHA 拼圖的預設地區設定。CAPTCHA 拼圖的書面指示提供阿拉伯文 (ar-SA)、簡體中文 (zh-CN)、荷蘭文 (nl-NL)、英文 (en-US)、法文 (fr-FR)、德文 (de-DE)、義大利文 (it-IT)、日文 (ja-JP)、巴西葡萄牙文 (pt-BR)、西班牙文 (es-ES) 和土耳其文 (tr-TR)。除了預設為英文的中文和日文以外，音訊指示適用於所有書面語言。若要變更預設語言，請提供國際語言和地區設定代碼，例如 `ar-SA`。  
預設：目前在最終使用者的瀏覽器中使用的語言  
必要：否  
類型：`string`  
**`disableLanguageSelector`**   
如果設定為 `true`，CAPTCHA 拼圖會隱藏語言選擇器。  
預設：`false`  
必要：否  
類型：`boolean`  
**`dynamicWidth`**   
如果設定為 `true`，CAPTCHA 拼圖會變更寬度，以符合瀏覽器視窗寬度。  
預設：`false`  
必要：否  
類型：`boolean`  
**`skipTitle`**   
如果設定為 `true`，CAPTCHA 拼圖不會顯示拼圖標題 **解決拼圖**。  
預設：`false`  
必要：否  
類型：`boolean`

# 如何轉譯 CAPTCHA 拼圖
<a name="waf-js-captcha-api-render"></a>

本節提供範例`renderCaptcha`實作。

您可以在 AWS WAF `renderCaptcha`用戶端界面中使用您想要的 呼叫。呼叫會從 擷取 CAPTCHA 拼圖 AWS WAF、轉譯它，並將結果傳送至 AWS WAF 以進行驗證。當您進行呼叫時，您會提供拼圖轉譯組態，以及在最終使用者完成拼圖時要執行的回呼。如需選項的詳細資訊，請參閱上一節：[CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)。

將此呼叫與智慧型威脅整合 APIs的字符管理功能搭配使用。此呼叫會為您的用戶端提供權杖，以驗證 CAPTCHA 拼圖是否成功完成。使用智慧型威脅整合 APIs 來管理字符，並在用戶端呼叫受 AWS WAF 保護套件 (Web ACLs) 保護的端點時提供字符。如需智慧型威脅 APIs的詳細資訊，請參閱 [使用智慧型威脅 JavaScript API](waf-js-challenge-api.md)。

**實作範例**  
下列範例清單顯示標準 CAPTCHA 實作，包括在 `<head>`區段中放置 AWS WAF 整合 URL。

此清單使用使用智慧型威脅整合 APIs `AwsWafIntegration.fetch`包裝函式的成功回呼來設定`renderCaptcha`函數。如需此函數的資訊，請參閱 [如何使用整合`fetch`包裝函式](waf-js-challenge-api-fetch-wrapper.md)。

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Captcha completed. wafToken contains a valid WAF token. Store it for
        // use later or call AwsWafIntegration.fetch() to use it easily.
        // It will expire after a time, so calling AwsWafIntegration.getToken()
        // again is advised if the token is needed later on, outside of using the
        // fetch wrapper.
        
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: "{ ... }" /* body content */
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**範例組態設定**  
下列範例清單顯示`renderCaptcha`具有寬度和標題選項非預設設定的 。

```
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            dynamicWidth: true, 
            skipTitle: true
        });
```

如需組態選項的完整資訊，請參閱 [CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)。

# 從 處理 CAPTCHA 回應 AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

本節提供處理 CAPTCHA 回應的範例。

如果請求沒有具有有效 CAPTCHA 時間戳記的字符，則具有CAPTCHA動作的 AWS WAF 規則會終止對相符 Web 請求的評估。如果請求是`GET`文字/html 呼叫，則CAPTCHA動作會為用戶端提供具有 CAPTCHA 拼圖的間質。當您未整合 CAPTCHA JavaScript API 時，間質會執行拼圖，如果最終使用者成功解決， 會自動重新提交請求。

當您整合 CAPTCHA JavaScript API 並自訂 CAPTCHA 處理時，您需要偵測終止的 CAPTCHA 回應、提供自訂 CAPTCHA，然後如果最終使用者成功解決拼圖，請重新提交用戶端的 Web 請求。

下列程式碼範例示範其做法：

**注意**  
 AWS WAF CAPTCHA 動作回應的狀態碼為 HTTP 405，用於辨識此程式碼中的CAPTCHA回應。如果您的受保護端點使用 HTTP 405 狀態碼來通訊相同呼叫的任何其他回應類型，則此範例程式碼也會轉譯這些回應的 CAPTCHA 拼圖。

```
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>
<body>
    <div id="my-captcha-box"></div>
    <div id="my-output-box"></div>

    <script type="text/javascript">
    async function loadData() {
        // Attempt to fetch a resource that's configured to trigger a CAPTCHA
        // action if the rule matches. The CAPTCHA response has status=HTTP 405.
        const result = await AwsWafIntegration.fetch("/protected-resource");

        // If the action was CAPTCHA, render the CAPTCHA and return

        // NOTE: If the endpoint you're calling in the fetch call responds with HTTP 405
        // as an expected response status code, then this check won't be able to tell the
        // difference between that and the CAPTCHA rule action response.

        if (result.status === 405) {
            const container = document.querySelector("#my-captcha-box");
            AwsWafCaptcha.renderCaptcha(container, {
                apiKey: "...API key goes here...",
                onSuccess() {
                    // Try loading again, now that there is a valid CAPTCHA token
                    loadData();
                },
            });
            return;
        }

        const container = document.querySelector("#my-output-box");
        const response = await result.text();
        container.innerHTML = response;
    }

    window.addEventListener("load", () => {
        loadData();
    });
    </script>
</body>
</html>
```

# 管理 JS CAPTCHA API 的 API 金鑰
<a name="waf-js-captcha-api-key"></a>

本節提供產生和刪除 API 金鑰的指示。

若要將 AWS WAF CAPTCHA 與 JavaScript API 整合到用戶端應用程式，您需要要執行 CAPTCHA 拼圖之用戶端網域的 JavaScript API 整合標籤和加密的 API 金鑰。

JavaScript 的 CAPTCHA 應用程式整合 JavaScript 使用加密的 API 金鑰來驗證用戶端應用程式網域是否具有使用 AWS WAF CAPTCHA API 的許可。當您從 JavaScript 用戶端呼叫 CAPTCHA API 時，您會提供具有網域清單的 API 金鑰，其中包含目前用戶端的網域。您可以在單一加密金鑰中列出最多 5 個網域。

**API 金鑰需求**  
您在 CAPTCHA 整合中使用的 API 金鑰必須包含套用至您使用金鑰之用戶端的網域。
+ 如果您在用戶端的智慧型威脅整合`window.awsWafCookieDomainList`中指定 ，則 API 金鑰中的至少一個網域必須完全符合 中的其中一個字符網域，`window.awsWafCookieDomainList`或者必須是其中一個字符網域的頂點網域。

  例如，對於字符網域 `mySubdomain.myApex.com`，API 金鑰`mySubdomain.myApex.com`是完全相符的，API 金鑰`myApex.com`是頂點網域。任一金鑰都符合字符網域。

  如需設定字符網域清單的相關資訊，請參閱 [提供用於字符的網域](waf-js-challenge-api-set-token-domain.md)。
+ 否則，目前的網域必須包含在 API 金鑰中。目前的網域是您可以在瀏覽器地址列中看到的網域。

您使用的網域必須是 AWS WAF 根據受保護的主機網域和為 Web ACL 設定的字符網域清單而接受的網域。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。

**如何選擇 API 金鑰的區域**  
AWS WAF 可以在可使用 的任何區域中產生 CAPTCHA API AWS WAF 金鑰。

一般而言，您應該使用與保護套件 (Web ACL) 相同的 CAPTCHA API 金鑰區域。不過，如果您預期全球受眾使用區域保護套件 (Web ACL)，您可以取得範圍為 CloudFront 的 CAPTCHA JavaScript 整合標籤，以及範圍為 CloudFront 的 API 金鑰，並將其與區域保護套件 (Web ACL) 搭配使用。此方法可讓用戶端從最接近它們的區域載入 CAPTCHA 拼圖，從而減少延遲。

範圍限定在 CloudFront 以外區域的 CAPTCHA API 金鑰不支援跨多個區域使用。它們只能在其範圍範圍內的區域中使用。

**為您的用戶端網域產生 API 金鑰**  
取得整合 URL，並透過主控台產生和擷取 API 金鑰。

1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。

1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。

1. 在**已啟用應用程式整合的保護套件 (Web ACLs)** 窗格中，選取您要用於 API 金鑰的區域。您也可以在 **CAPTCHA 整合**索引標籤的 **API 金鑰**窗格中選取區域。

1. 選擇 **CAPTCHA 整合**索引標籤。此索引標籤提供 CAPTCHA JavaScript 整合標籤，您可以在整合中使用，以及 API 金鑰清單。兩者的範圍都限定為選取的區域。

1. 在 **API 金鑰**窗格中，選擇**產生金鑰**。金鑰產生對話隨即出現。

1. 輸入您要包含在金鑰中的用戶端網域。您最多可以輸入 5 個。完成後，請選擇**產生金鑰**。界面會返回列出新金鑰的 CAPTCHA 整合索引標籤。

   建立後，API 金鑰是不可變的。如果您需要變更金鑰，請產生新的金鑰並改用該金鑰。

1. （選用） 複製新產生的金鑰以用於整合。

您也可以為此工作使用 REST APIs 或其中一種特定語言 AWS SDKs。REST API 呼叫是 [CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) 和 [ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html)。

**刪除 API 金鑰**  
若要刪除 API 金鑰，您必須使用 REST API 或其中一種語言 AWS SDKs。REST API 呼叫是 [DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html)。您無法使用 主控台刪除金鑰。

刪除金鑰後， 最多可能需要 24 小時 AWS WAF 才能禁止在所有區域中使用金鑰。

# AWS WAF 行動應用程式整合
<a name="waf-mobile-sdk"></a>

本節介紹使用 AWS WAF 行動 SDKs實作適用於 Android 和 iOS 行動和電視應用程式的 AWS WAF 智慧型威脅整合 SDKs 的主題。對於電視應用程式，SDKs與主要智慧型電視平台相容，包括 Android TV 和 Apple TV。
+ 對於 Android 行動和電視應用程式，SDKs適用於 Android API 第 23 版 (Android 第 6 版） 和更新版本。如需 Android 版本的資訊，請參閱 [SDK 平台版本備註](https://developer.android.com/tools/releases/platforms)。
+ 對於 iOS 行動應用程式，SDKs適用於 iOS 版本 13 和更新版本。如需 iOS 版本的資訊，請參閱 [iOS & iPadOS 版本備註](https://developer.apple.com/documentation/ios-ipados-release-notes)。
+ 對於 Apple TV 應用程式，SDKs適用於 tvOS 第 14 版或更新版本。如需 tvOS 版本的資訊，請參閱 [tvOS 版本備註](https://developer.apple.com/documentation/tvos-release-notes)。

透過行動 AWS WAF 開發套件，您可以管理權杖授權，並將權杖包含在傳送至受保護資源的請求中。透過使用 SDKs，您可以確保用戶端進行的這些遠端程序呼叫包含有效的字符。此外，當您的應用程式頁面上有此整合時，您可以在保護套件 (Web ACL) 中實作緩解規則，例如封鎖不包含有效字符的請求。

如需存取行動SDKs，請聯絡 [Contact AWS](https://aws.amazon.com/contact-us) 的支援。

**注意**  
 AWS WAF 行動 SDKs 不適用於 CAPTCHA 自訂。

使用 SDK 的基本方法是使用組態物件建立權杖提供者，然後使用權杖提供者從中擷取權杖 AWS WAF。根據預設，權杖提供者會在對受保護資源的 Web 請求中包含擷取的權杖。

以下是 SDK 實作的部分清單，其中顯示主要元件。如需更詳細的範例，請參閱[AWS WAF 行動 SDK 的程式碼範例](waf-mobile-sdk-coding-examples.md)。

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
	let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
	let tokenProvider = WAFTokenProvider(configuration)
	let token = tokenProvider.getToken()
```

------
#### [ Android ]

```
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");
	String domainName = "Domain name";
	WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
	WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);
	WAFToken token = tokenProvider.getToken();
```

------

# 安裝 AWS WAF 行動 SDK
<a name="waf-mobile-sdk-installing"></a>

本節提供安裝 AWS WAF 行動 SDK 的說明。

如需存取行動SDKs，請聯絡 [Contact AWS](https://aws.amazon.com/contact-us) 的支援。

先在測試環境中實作行動 SDK，然後在生產環境中實作。

**安裝 AWS WAF 行動 SDK**

1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。

1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。

1. 在**智慧型威脅整合**索引標籤中，執行下列動作：

   1. 在**已啟用應用程式整合的窗格保護套件 (Web ACLs)** 中，找到您要整合的保護套件 (Web ACL)。複製並儲存保護套件 (Web ACL) 整合 URL 以用於您的實作。您也可以透過 API 呼叫 取得此 URL`GetWebACL`。

   1. 選擇行動裝置類型和版本，然後選擇**下載**。您可以選擇任何您喜歡的版本，但我們建議您使用最新版本。 會將您裝置的 `zip` 檔案 AWS WAF 下載到您的標準下載位置。

1. 在您的應用程式開發環境中，將檔案解壓縮到您選擇的工作位置。在 zip 檔案的最上層目錄中，找到並開啟 `README`。依照 `README` 檔案中的指示，安裝 AWS WAF 行動 SDK 以用於您的行動應用程式程式碼。

1. 根據以下章節中的指引來設定您的應用程式。

# AWS WAF 行動 SDK 規格
<a name="waf-mobile-sdk-specification"></a>

本節列出 AWS WAF 行動 SDK 最新可用版本的 SDK 物件、操作和組態設定。如需字符提供者和操作如何針對各種組態設定組合運作的詳細資訊，請參閱 [AWS WAF 行動開發套件的運作方式](waf-mobile-sdk-how-it-works.md)。

**`WAFToken`**  
保留權 AWS WAF 杖。    
**`getValue()`**  
擷取 的`String`表示法`WAFToken`。

**`WAFTokenProvider`**  
管理行動應用程式中的字符。使用 `WAFConfiguration` 物件實作此項目。    
**`getToken()`**  
如果已啟用背景重新整理，這會傳回快取的字符。如果停用背景重新整理，這會導致同步，封鎖呼叫 AWS WAF 以擷取新的字符。  
**`loadTokenIntoProvider(WAFToken)`**  
將指定的權杖載入 `WAFTokenProvider`，取代提供者管理的任何權杖。權杖提供者會取得新權杖的所有權，並在未來處理重新整理權杖。如果在 中`setTokenCookie`啟用 ，此操作也會更新 Cookie 存放區中的字符`WAFConfiguration`。  
**`onTokenReady(WAFTokenResultCallback)`**  
指示權杖提供者重新整理權杖，並在作用中權杖就緒時叫用提供的回呼。當字符快取並就緒時，字符提供者會在背景執行緒中叫用您的回呼。當您的應用程式第一次載入時，以及它回到作用中狀態時，請呼叫此選項。如需返回作用中狀態的詳細資訊，請參閱 [在應用程式閒置後擷取字符](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive)。  
對於 Android 或 iOS 應用程式，您可以將 `WAFTokenResultCallback` 設定為您希望權杖提供者在請求權杖就緒時叫用的操作。您的 實作`WAFTokenResultCallback`必須採用參數 `WAFToken`、`SdkError`。對於 iOS 應用程式，您可以交替建立內嵌函數。  
**`storeTokenInCookieStorage(WAFToken)`**  
指示 將指定的 AWS WAF 字符`WAFTokenProvider`存放到開發套件的 Cookie 管理員。根據預設，字符只會在第一次取得和重新整理時新增至 Cookie 存放區。如果應用程式因任何原因清除共用的 Cookie 存放區，軟體開發套件不會自動新增 AWS WAF 字符，直到下一次重新整理為止。

**`WAFConfiguration`**  
保留 實作的組態`WAFTokenProvider`。當您實作此項目時，您會提供保護套件 (Web ACL) 的整合 URL、要在字符中使用的網域名稱，以及您希望字符提供者使用的任何非預設設定。  
下列清單指定您可以在 `WAFConfiguration` 物件中管理的組態設定。    
**`applicationIntegrationUrl`**   
應用程式整合 URL。從 AWS WAF 主控台或透過 `getWebACL` API 呼叫取得。  
必要：是  
類型：應用程式特定的 URL。對於 iOS，請參閱 [iOS URL](https://developer.apple.com/documentation/foundation/url)。對於 Android，請參閱 [java.net URL](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html)。  
**`backgroundRefreshEnabled`**   
指出您是否希望權杖提供者在背景重新整理權杖。如果您設定此項目，權杖提供者會根據管理自動權杖重新整理活動的組態設定，在背景重新整理權杖。  
必要：否  
類型：`Boolean`  
預設值：`TRUE`  
**`domainName`**   
要在字符中使用的網域，用於字符獲取和 Cookie 儲存。例如 `example.com` 或 `aws.amazon.com`。這通常是與保護套件 (Web ACL) 相關聯的 資源的主機網域，您將在其中傳送 Web 請求。對於 ACFP 受管規則群組 `AWSManagedRulesACFPRuleSet`，這通常是與您在規則群組組態中提供的帳戶建立路徑中的網域相符的單一網域。對於 ATP 受管規則群組 `AWSManagedRulesATPRuleSet`，這通常是與您在規則群組組態中提供的登入路徑中的網域相符的單一網域。  
不允許公有尾碼。例如，您無法使用 `gov.au`或 `co.uk`做為字符網域。  
根據受保護的主機網域和保護套件 (Web ACL) 的字符網域清單，網域必須是 AWS WAF 將接受的網域。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。  
必要：是  
類型：`String`  
**`maxErrorTokenRefreshDelayMsec`**   
嘗試失敗後重複權杖重新整理之前等待的時間上限，以毫秒為單位。對於失敗嘗試的每個自動重試，它會新增指數退避，直到指定的輸入延遲時間為止。此值會在字符擷取失敗並重試`maxRetryCount`時間後使用。  
必要：否  
類型：`Integer`  
預設值：`5000`(5 秒）  
允許的最小值： `1` (1 毫秒）  
允許的最大值：`30000`(30 秒）  
**`maxRetryCount`**   
請求權杖時，以指數退避執行的重試次數上限。  
必要：否  
類型：`Integer`  
預設值：`Infinity`  
允許的最小值： `0`  
允許的最大值： `100`  
**`setTokenCookie`**   
指出您是否希望開發套件的 Cookie 管理員將權杖 Cookie 新增至請求和其他區域。  
使用 `TRUE`值：  
+ Cookie 管理員會將權杖 Cookie 新增至路徑位於 中指定路徑下的所有請求`tokenCookiePath`。
+ 除了將權杖載入權杖提供者之外， `WAFTokenProvider`操作還會`loadTokenIntoProvider()`更新 Cookie 存放區中的權杖。
必要：否  
類型：`Boolean`  
預設值：`TRUE`  
**`tokenCookiePath`**   
當 `setTokenCookie`為 時使用`TRUE`。指出您希望開發套件的 Cookie 管理員新增字符 Cookie 的頂層路徑。管理員會將權杖 Cookie 新增至您傳送至此路徑和所有子路徑的所有請求。  
例如，如果您將此設定為 `/web/login`，則管理員會包含傳送至 的所有項目`/web/login`及其任何子路徑的字符 Cookie，例如 `/web/login/help`。它不包含傳送至其他路徑之請求的字符，例如 `/`、 `/web`或 `/web/order`。  
必要：否  
類型：`String`  
預設值：`/`  
**`tokenRefreshDelaySec`**   
用於背景重新整理。背景權杖重新整理之間的秒數上限。  
必要：否  
類型：`Integer`  
預設值：`88`  
允許的最小值： `88`  
允許的最大值：`300`(5 分鐘）

## AWS WAF 行動 SDK 錯誤
<a name="waf-mobile-sdk-errors"></a>

本節列出目前 AWS WAF 行動 SDK 版本的可能錯誤。

**`SdkError`**  
無法擷取字符時傳回的錯誤類型。Android 和 iOS 開發套件具有相同的錯誤類型。  
 AWS WAF 行動開發套件具有下列錯誤類型：    
**`invalidChallenge`**  
當字符伺服器傳回無效的挑戰資料，或攻擊者變更回應 Blob 時，會傳回此錯誤。  
**`errorInvokingGetChallengeEndpoint`**  
當字符伺服器傳送不成功的回應碼回用戶端或發生網路錯誤時，會傳回此錯誤。  
**`invalidVerifyChallengeResponse`**  
當`aws-waf-token`從 AWS WAF 伺服器的驗證回應擷取 時發生錯誤，或伺服器回應遭到竄改時，就會傳回此錯誤。  
**`errorInvokingVerifyEndpoint`**  
當用戶端在驗證已解決的挑戰時收到 AWS WAF 伺服器或網路錯誤的回應時，會傳回此錯誤。  
**`internalError`**  
此錯誤會在 SDK 本身可能發生的所有其他錯誤上傳回。

**`socketTimeoutException`**  
在權杖擷取期間遇到網路錯誤時，通常會傳回此錯誤。  
此錯誤可能由下列原因造成：  
+ 低網路頻寬：確認您的網路連線設定
+ 變動的應用程式整合 URL：確認整合 URL 未從 AWS WAF 主控台上顯示的內容修改

# AWS WAF 行動開發套件的運作方式
<a name="waf-mobile-sdk-how-it-works"></a>

本節說明 AWS WAF 行動 SDK 類別、屬性和操作如何一起運作。

行動SDKs為您提供可設定的字符提供者，可用於字符擷取和使用。字符提供者會驗證您允許的請求是否來自合法客戶。當您將請求傳送至 AWS 您保護的資源時 AWS WAF，您會在 Cookie 中包含權杖，以驗證請求。您可以手動處理權杖 Cookie，或讓權杖提供者為您處理權杖 Cookie。

本節涵蓋行動 SDK 中包含的類別、屬性和方法之間的互動。如需 SDK 規格，請參閱 [AWS WAF 行動 SDK 規格](waf-mobile-sdk-specification.md)。

## 權杖擷取和快取
<a name="waf-mobile-sdk-how-token-basics"></a>

當您在行動應用程式中建立權杖提供者執行個體時，您可以設定其管理權杖和權杖擷取的方式。您的主要選擇是如何維護有效、未過期的字符，以便在應用程式的 Web 請求中使用：
+ **已啟用背景重新整理** – 這是預設值。權杖提供者會在背景自動重新整理權杖並快取權杖。啟用背景重新整理後，當您呼叫 時`getToken()`，操作會擷取快取的字符。

  權杖提供者會以可設定的間隔執行權杖重新整理，讓未過期的權杖在應用程式作用中時一律可在快取中使用。當您的應用程式處於非作用中狀態時，背景重新整理會暫停。如需詳細資訊，請參閱 [在應用程式閒置後擷取字符](#waf-mobile-sdk-how-back-from-inactive)。
+ **背景重新整理已停用** – 您可以停用背景字符重新整理，然後僅隨需擷取字符。隨需擷取的權杖不會快取，您可以視需要擷取多個權杖。每個字符與您擷取的任何其他字符無關，每個字符都有自己的時間戳記，用於計算過期。

  停用背景重新整理時，您有下列權杖擷取選項：
  + **`getToken()`** – 當您呼叫`getToken()`時停用背景重新整理，呼叫會從中同步擷取新的字符 AWS WAF。如果您在主執行緒上調用應用程式回應能力，這可能會封鎖呼叫。
  + **`onTokenReady(WAFTokenResultCallback)`** – 此呼叫會以非同步方式擷取新的權杖，然後在權杖就緒時，在背景執行緒中調用提供的結果回呼。

### 字符提供者如何重試失敗的字符擷取
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

當擷取失敗時，字符提供者會自動重試字符擷取。一開始會使用指數退避執行重試，起始重試等待時間為 100 毫秒。如需指數重試的相關資訊，請參閱[錯誤重試和指數退避 AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。

當重試次數達到設定的 時`maxRetryCount`，字符提供者會停止嘗試或切換為每`maxErrorTokenRefreshDelayMsec`毫秒嘗試一次，取決於字符擷取的類型：
+ **`onTokenReady()`** – 權杖提供者會在嘗試之間切換到等待`maxErrorTokenRefreshDelayMsec`毫秒，並繼續嘗試擷取權杖。
+ **背景重新整理** – 權杖提供者會在嘗試之間切換到等待`maxErrorTokenRefreshDelayMsec`毫秒，並繼續嘗試擷取權杖。
+ **停用背景重新整理時的隨需`getToken()`呼叫** – 權杖提供者會停止嘗試擷取權杖，並傳回先前的權杖值，如果沒有先前的權杖，則會傳回 null 值。

## 字符擷取重試案例
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

當字符提供者嘗試擷取字符時，根據字符擷取在字符擷取流程中失敗的位置，可能會導致自動重試。本節列出您可能會看到自動重試的可能位置。
+ **透過 /inputs 或 /verify 取得或驗證 AWS WAF 挑戰：**
  + 當取得和驗證 AWS WAF 挑戰的請求提出且失敗時，可能會導致自動重試。
  + 您可能會看到自動重試與`socketTimeoutException`錯誤一起發生。這可能有多個原因，包括：
    + 低網路頻寬：確認您的網路連線設定
    + 變動的應用程式整合 URL：確認整合 URL 未從 AWS WAF 主控台上顯示的內容修改
  + 可使用 `maxRetryCount()`函數設定自動重試計數
+ **重新整理權杖：**
  + 透過權杖處理常式提出重新整理權杖的請求時，可能會導致自動重試。
  + 此處的自動重試計數可透過 `maxRetryCount()`函數設定。

設定 可進行沒有自動重試的組態`maxRetryCount(0)`。

## 字符抑制時間和背景重新整理
<a name="waf-mobile-sdk-how-token-immunity"></a>

您在 Web ACL 中設定的字符抗擾性時間與您在 AWS WAF 行動 SDK 中設定的字符重新整理間隔無關。當您啟用背景重新整理時，軟體開發套件會在您使用 指定的間隔重新整理字符`tokenRefreshDelaySec()`。這可能會導致多個有效的字符同時存在，取決於您設定的抗擾性時間。

若要防止多個有效字符，您可以停用背景重新整理，並使用 `getToken()`函數來管理行動應用程式中的字符生命週期。

## 在應用程式閒置後擷取字符
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

只有在您的應用程式視為應用程式類型的作用中時，才會執行背景重新整理：
+ **iOS** – 背景重新整理會在應用程式位於前景時執行。
+ **Android** – 背景重新整理會在應用程式未關閉時執行，無論是在前景或背景中。

如果您的應用程式保持在不支援背景重新整理的任何狀態超過設定的`tokenRefreshDelaySec`秒數，字符提供者會暫停背景重新整理。例如，對於 iOS 應用程式，如果 `tokenRefreshDelaySec`是 300 且應用程式關閉或進入背景超過 300 秒，字符提供者會停止重新整理字符。當應用程式返回作用中狀態時，字符提供者會自動重新啟動背景重新整理。

當您的應用程式回到作用中狀態時，請呼叫 `onTokenReady()`，以便在權杖提供者擷取和快取新的權杖時收到通知。不要只呼叫 `getToken()`，因為快取可能尚未包含目前有效的字符。

## 應用程式整合 URL
<a name="waf-mobile-sdk-application-integration-url"></a>

 AWS WAF 行動 SDK 應用程式整合 URL 指向您已啟用的應用程式整合的 Web ACL。此 URL 會將請求路由至正確的後端伺服器，並將其與您的客戶建立關聯。它不做為硬式安全控制，因此公開整合 URL 不會帶來安全風險。

您可以在技術上修改提供的整合 URL，但仍取得權杖。不過，我們不建議這麼做，因為您可能會失去對挑戰解決率的可見性，或遇到字符擷取失敗並`socketTimeoutException`發生錯誤。

## 相依性
<a name="waf-mobile-sdk-dependencies"></a>

每個可下載 AWS WAF 的行動 SDK 都包含一個 README 檔案，列出其特定版本 SDK 的相依性。如需行動 SDK 版本的相依性，請參閱 README。

## Obfuscation/ProGuard （僅限 Android 開發套件）
<a name="waf-mobile-sdk-obfuscation"></a>

如果您使用 ProGuard 之類的混淆或縮小產品，您可能需要排除某些命名空間，以確保行動 SDK 正常運作。檢查行動開發套件版本的 README，以尋找命名空間和排除規則的清單。

# AWS WAF 行動 SDK 的程式碼範例
<a name="waf-mobile-sdk-coding-examples"></a>

本節提供使用行動 SDK 的程式碼範例。

## 初始化權杖提供者並取得權杖
<a name="waf-mobile-sdk-coding-basic"></a>

您可以使用組態物件啟動權杖提供者執行個體。然後，您可以使用可用的操作擷取權杖。以下顯示必要程式碼的基本元件。

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
let tokenProvider = WAFTokenProvider(configuration)

//onTokenReady can be add as an observer for UIApplication.willEnterForegroundNotification
self.tokenProvider.onTokenReady() { token, error in
	if let token = token {
	//token available
	}

	if let error = error {
	//error occurred after exhausting all retries
	}
}

//getToken()
let token = tokenProvider.getToken()
```

------
#### [ Android ]

Java 範例：

```
String applicationIntegrationURL = "protection pack (web ACL) integration URL";
//Or
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");

String domainName = "Domain name";

WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);

// implement a token result callback
WAFTokenResultCallback callback = (wafToken, error) -> {
	if (wafToken != null) {
	// token available
	} else {  
	// error occurred in token refresh  
	}
};

// Add this callback to application creation or activity creation where token will be used
tokenProvider.onTokenReady(callback);

// Once you have token in token result callback
// if background refresh is enabled you can call getToken() from same tokenprovider object
// if background refresh is disabled you can directly call getToken()(blocking call) for new token
WAFToken token = tokenProvider.getToken();
```

Kotlin 範例：

```
import com.amazonaws.waf.mobilesdk.token.WAFConfiguration
import com.amazonaws.waf.mobilesdk.token.WAFTokenProvider

private lateinit var wafConfiguration: WAFConfiguration
private lateinit var wafTokenProvider: WAFTokenProvider

private val WAF_INTEGRATION_URL = "protection pack (web ACL) integration URL"
private val WAF_DOMAIN_NAME = "Domain name"

fun initWaf() {
	// Initialize the tokenprovider instance
	val applicationIntegrationURL = URL(WAF_INTEGRATION_URL)
	wafConfiguration =
		WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL)
			.domainName(WAF_DOMAIN_NAME).backgroundRefreshEnabled(true).build()
	wafTokenProvider = WAFTokenProvider(getApplication(), wafConfiguration)
	
		// getToken from tokenprovider object
		println("WAF: "+ wafTokenProvider.token.value)
	
		// implement callback for where token will be used
		wafTokenProvider.onTokenReady {
			wafToken, sdkError ->
		run {
			println("WAF Token:" + wafToken.value)
		}
	}
}
```

------

## 允許 SDK 在 HTTP 請求中提供字符 Cookie
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

如果 `setTokenCookie`是 `TRUE`，權杖提供者會在 Web 請求中，將權杖 Cookie 包含到 中指定路徑下的所有位置`tokenCookiePath`。根據預設，`setTokenCookie` 為 `TRUE`，而 `tokenCookiePath`為 `/`。

您可以透過指定字符 Cookie 路徑來縮小包含字符 Cookie 的請求範圍，例如 `/web/login`。如果您這樣做，請檢查您的 AWS WAF 規則是否在您傳送至其他路徑的請求中檢查字符。使用`AWSManagedRulesACFPRuleSet`規則群組時，您可以設定帳戶註冊和建立路徑，而規則群組會檢查傳送至這些路徑之請求中的字符。如需詳細資訊，請參閱[將 ACFP 受管規則群組新增至 Web ACL](waf-acfp-rg-using.md)。同樣地，當您使用`AWSManagedRulesATPRuleSet`規則群組時，您可以設定登入路徑，而規則群組會檢查傳送至該路徑之請求中的字符。如需詳細資訊，請參閱[將 ATP 受管規則群組新增至保護套件 (Web ACL)](waf-atp-rg-using.md)。

------
#### [ iOS ]

當 `setTokenCookie`為 時`TRUE`，字符提供者會將 AWS WAF 字符存放在 中，`HTTPCookieStorage.shared`並在對您在 中指定的網域的請求中自動包含 Cookie`WAFConfiguration`。

```
let request = URLRequest(url: URL(string: domainEndpointUrl)!)
//The token cookie is set automatically as cookie header
let task = URLSession.shared.dataTask(with: request) { data, urlResponse, error  in
}.resume()
```

------
#### [ Android ]

當 `setTokenCookie`為 時`TRUE`，字符提供者會將 AWS WAF 字符存放在整個共用應用程式的`CookieHandler`執行個體中。權杖提供者會自動將 Cookie 包含在對您在 中指定之網域的請求中`WAFConfiguration`。

Java 範例：

```
URL url = new URL("Domain name");
//The token cookie is set automatically as cookie header
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.getResponseCode();
```

Kotlin 範例：

```
val url = URL("Domain name")
//The token cookie is set automatically as cookie header
val connection = (url.openConnection() as HttpsURLConnection)
connection.responseCode
```

如果您已初始化`CookieHandler`預設執行個體，字符提供者將使用它來管理 Cookie。如果沒有，字符提供者將使用 AWS WAF 字符初始化新的`CookieManager`執行個體，`CookiePolicy.ACCEPT_ORIGINAL_SERVER`然後將此新執行個體設定為 中的預設執行個體`CookieHandler`。

下列程式碼顯示 SDK 如何在您的應用程式中無法使用 Cookie 管理員和 Cookie 處理常式時初始化 Cookie 管理員和 Cookie 處理常式。

Java 範例：

```
CookieManager cookieManager = (CookieManager) CookieHandler.getDefault();
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = new CookieManager();
	CookieHandler.setDefault(cookieManager);
}
```

Kotlin 範例：

```
var cookieManager = CookieHandler.getDefault() as? CookieManager
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = CookieManager()
	CookieHandler.setDefault(cookieManager)
}
```

------

## 在 HTTP 請求中手動提供字符 Cookie
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

如果您將 `setTokenCookie`設定為 `FALSE`，則需要在對受保護端點的請求中，以 Cookie HTTP 請求標頭的形式手動提供字符 Cookie。下列程式碼示範如何執行此操作。

------
#### [ iOS ]

```
var request = URLRequest(url: wafProtectedEndpoint)
request.setValue("aws-waf-token=token from token provider", forHTTPHeaderField: "Cookie")
request.httpShouldHandleCookies = true
URLSession.shared.dataTask(with: request) { data, response, error in }
```

------
#### [ Android ]

Java 範例：

```
URL url = new URL("Domain name");
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
String wafTokenCookie = "aws-waf-token=token from token provider";
connection.setRequestProperty("Cookie", wafTokenCookie);
connection.getInputStream();
```

Kotlin 範例：

```
val url = URL("Domain name")
val connection = (url.openConnection() as HttpsURLConnection)
val wafTokenCookie = "aws-waf-token=token from token provider"
connection.setRequestProperty("Cookie", wafTokenCookie)
connection.inputStream
```

------