Integrate with the KWS API

如需触发家长验证（PV）服务流程，你的 product 需要调用发送家长邮件API端点。

如需调用KWS API，你需要准备好特定的数据项，以便启用访问和验证功能。

在 集成信息（Integration information） 选项卡中，复制这些细节：

• 产品ID（Product ID） - 你的产品的KWS ID。
• 产品客户端ID（Product client ID） - 用于身份验证。
• 产品API密钥（Product API key） - 客户端密钥，用于获取开发者访问令牌。

点击查看大图。

在 家长验证 选项卡中，复制以下信息：

• Webhook密钥代码 - 用于签署负载（payload），以确保它是来自KWS的真实调用。
• 服务API主机URL - PV服务所在的URL。使用API查询时应使用此URL。

点击查看大图。

你必须配置你的产品，收集以下内容：

• 家长的电子邮件地址。
• 儿童的位置。可以是以下一种：
  • ISO 3166-1 alpha-2，例如：'US'、'GB'、'CA'。
  • 公认的ISO 3166-2细分代码，例如，'US-CA'、'GB-ENG'、'CA-BC'。
• 家长使用的语言。这是KWS在电子邮件中以及显示验证界面时使用的语言。 例如，'en'、'de'、'ja'。有关受支持语言的完整列表，请参阅PV服务本地化。

配置你的产品，通过使用验证过的API并向send-parent-email端点发送调用，将你收集到的家长的电子邮件地址、儿童位置以及家长使用的语言发送给KWS。

发送频率限制为具体次数，具体为每个家长电子邮件地址每小时最多10次请求。

所有对KWS API的请求都必须包含一个用户代理标头，其中包含一个非空字符串，以识别你的客户端和/或HTTP库。否则，将导致“请求被阻止”的403响应。

API调用必须通过名为“开发者访问令牌”的Bearer令牌进行认证。

使用 client_credentials OAuth，从KWS验证服务获取开发者访问令牌。OAuth来自令牌端点。你还需要用到 产品客户端ID 和 产品API密钥 (客户端密钥)来自 集成信息 选项卡。

如需获取令牌：

所有与KWS API集成的系统都应该为API调用实现一个重试机制。如果实现了重试机制，它必须执行指数退避（exponential backoff），并遵循API调用发送的任意的频率限制标头。

调用KWS的API后，KWS会负责管理整个验证流程：

1. KWS向所提供的家长电子邮件地址发送一封电子邮件，要求家长确认他们的身份。
2. 家长点击邮件中的链接，启动验证流程。
3. KWS向家长展示一个基于网络界面，家长可以在其中输入他们的验证凭证。根据儿童位置和你选择呈现给家长的验证方法，会使用不同的验证方法。
4. 验证成功后：

   • KWS会使用你配置的Webhook将 'parent-verified' 事件发送回你的系统：

   • 家长的电子邮件地址的哈希值保存在KWS ParentGraph中。这使KWS在下次遇到PV服务时能确定家长是否预先被验证过。

     预先验证过的家长不必再提供验证凭证。‘预先验证’ 是指家长的哈希电子邮件地址已经包含在ParentGraph中，并且家长先前已被KWS PV服务验证过，该验证方法对所访问的产品是有效的（或在验证时是有效的）。

   • KWS会向家长发送一封确认邮件，通知他们已经成功验证并添加到ParentGraph中。（该邮件还包含一个退出ParentGraph的链接。）在某些涉及付款信息的验证方法中，该电子邮件还会包含有关授权、入账（Capture）和退款的细节，具体取决于儿童所在国家的要求。

   • 如果你在开发者门户中提供了一个 重定向URL，KWS会将家长重定向到该URL。 否则，KWS会在PV服务网页中显示一条验证成功的信息。

请参见PV服务用例，了解KWS向家长展示的电子邮件和网页视图的案例。

将你自己的自定义品牌应用于PV服务。