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

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

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

# 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，以尋找命名空間和排除規則的清單。