**引入全新的主机体验 Amazon WAF**
现在，您可以使用更新的体验访问控制台中任意位置的 Amazon WAF 功能。有关更多详细信息，请参阅[使用控制台](https://docs.amazonaws.cn/waf/latest/developerguide/working-with-console.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon WAF 移动 SDK 规范
本节列出了最新可用版本的 Amazon WAF 移动软件开发工具包的软件开发工具包对象、操作和配置设置。有关令牌提供程序和操作如何处理各种配置设置组合的详细信息，请参阅 [Amazon WAF 移动 SDK 的工作原理](waf-mobile-sdk-how-it-works.md)。
**`WAFToken`**
持有 Amazon WAF 代币。
**`getValue()`**
检索 `WAFToken` 的 `String` 表示形式。
**`WAFTokenProvider`**
在您的移动应用程序中管理令牌。使用 `WAFConfiguration` 对象实施此目的。
**`getToken()`**
如果启用了后台刷新，则会返回缓存的令牌。如果禁用了后台刷新，则会对进行同步阻塞调用 Amazon WAF 以检索新令牌。
**`loadTokenIntoProvider(WAFToken)`**
将指定的令牌加载到 `WAFTokenProvider`，替换提供者管理的所有令牌。令牌提供者具备新令牌的所有权，并负责日后对其进行刷新。如果在 `WAFConfiguration` 中启用 `setTokenCookie`，此操作还会更新 cookie 存储中的令牌。
**`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)`**
指示将指定的 Amazon WAF 令牌存储`WAFTokenProvider`到软件开发工具包的 Cookie 管理器中。默认情况下，只有在首次获取令牌和刷新令牌时，才会将其添加到 Cookie 存储中。如果应用程序出于任何原因清除了共享 Cookie 存储，则在下次刷新之前，SDK 不会自动重新添加 Amazon WAF 令牌。
**`WAFConfiguration`**
保存 `WAFTokenProvider` 实施的配置。实施此操作时，您需要提供保护包（web ACL）的集成 URL、要在令牌中使用的域名以及您希望令牌提供程序使用的任何非默认设置。
以下列表指定了可以在 `WAFConfiguration` 对象中管理的配置设置。
**`applicationIntegrationUrl`**
应用程序集成 URL。从 Amazon 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) 的令牌域列表，该域必须是可以接受的域。 Amazon WAF 有关更多信息，请参阅 [Amazon 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`**
表示您是否希望 SDK 的 cookie 管理器在请求或其他区域中添加令牌 cookie。
使用 `TRUE` 值：
+ cookie 管理器会向路径在 `tokenCookiePath` 中所指定路径之下的所有请求添加令牌 cookie。
+ 除将令牌加载到令牌提供程序以外，`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 分钟）
## Amazon WAF 移动 SDK 错误
本节列出了当前 Amazon WAF 移动 SDK 版本可能出现的错误。
**`SdkError`**
无法检索令牌时返回的错误类型。Android SDK 和 iOS SDK 的错误类型相同。
移 Amazon WAF 动 SDK 有以下错误类型：
**`invalidChallenge`**
当令牌服务器返回无效的质询数据，或者响应 blob 被攻击者改变时，就会返回此错误。
**`errorInvokingGetChallengeEndpoint`**
当令牌服务器向客户端发送不成功的响应代码或出现网络错误时，就会返回此错误。
**`invalidVerifyChallengeResponse`**
如果`aws-waf-token`从服务器的验证响应中检索时出错，或者 Amazon WAF 服务器响应被篡改，则会返回此错误。
**`errorInvokingVerifyEndpoint`**
当客户端收到 Amazon WAF 服务器的错误响应或验证已解决的挑战时出现网络错误时，就会返回此错误。
**`internalError`**
SDK 本身可能发生的所有其他错误都会返回此错误。
**`socketTimeoutException`**
当检索令牌时出现网络错误，通常会返回此错误。
此错误可能由于下列原因导致：
+ 网络带宽低：确认您的网络连接设置
+ 变更后的应用程序集成 URL：确认集成 URL 未与控制台上显示的内容相比进行修改 Amazon WAF