跳到主要内容

挑战

当玩家的年龄需要可验证父母同意 (VPC) 时，k-ID 会创建一个同意挑战，必须由可信成人批准，玩家才能访问游戏或功能。

挑战创建​

当使用需要父母同意的出生日期调用 /age-gate/check 时，会自动创建挑战。挑战信息在响应中返回：

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

挑战信息​

创建挑战时，您会收到：

  • challengeId：挑战的唯一标识符（存储此以供以后使用）
  • oneTimePassword：父母可以输入的密码以访问同意门户
  • url：可以呈现为二维码以便移动访问的 URL

显示挑战​

有关显示挑战和显示哪些信息的信息，请参阅核心概念部分的 挑战。

通知可信成人​

有几种方法可以通知可信成人有关同意挑战。有关通知方法的详细信息，请参阅核心概念部分的 挑战。

电子邮件通知​

如果玩家提供了父母或监护人的电子邮件地址，使用挑战 ID 和电子邮件地址调用 /challenge/send-email：

POST /api/v1/challenge/send-email
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
  "email": "parent@example.com"
}

或者，您可以在不指定电子邮件地址的情况下调用 /challenge/send-email，API 会向最近为玩家批准权限的可信成人发送电子邮件。如果未找到关联的电子邮件地址，API 会响应 INVALID_EMAIL 错误代码。

检查挑战状态​

显示同意挑战后，等待可信成人完成同意过程。您可以通过两种方式检查挑战状态：

Webhooks（推荐）​

有关 webhook 事件结构的详细信息，请参阅 Challenge.StateChange。

配置 webhook 端点以接收 Challenge.StateChange 事件。更多信息，请参阅 Webhooks。

轮询​

使用挑战 ID 定期轮询 /challenge/get-status API：

GET /api/v1/challenge/get-status?challengeId=683409f1-2930-4132-89ad-827462eed9af
Authorization: Bearer your-api-key

挑战状态可以是：

  • PASS：可信成人已授予同意
  • FAIL：请求被拒绝
  • PENDING：挑战仍在等待响应
  • POLL_TIMEOUT：已达到轮询超时（使用带超时的轮询时）

PASS 响应示例​

{
  "status": "PASS",
  "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
  "approverEmail": "parent@example.com"
}

等待同意​

在此期间可能会对 /challenge/get-status API 进行多次调用。在对 /challenge/get-status 的调用之间，应该有至少 5 秒的延迟。此外，/challenge/get-status 可能返回 HTTP 代码 429。游戏在处理 429 响应时应实施适当的重试逻辑。

有关等待同意和等待多长时间的更多信息，请参阅核心概念部分的 挑战。

待处理的同意挑战​

当从 /age-gate/check 返回 CHALLENGE 状态时，返回的挑战 ID 应该在挑战活动时存储在本地存储中。当游戏启动时存在活动挑战会引导游戏显示之前的相同同意挑战窗口。从本地存储检索挑战 ID 后，应该调用 /challenge/get API 以检索有关当前挑战的信息，包括一次性密码和二维码 URL，并且应该再次向用户显示挑战窗口。

更多信息，请参阅核心概念部分的 挑战。

挑战过期​

虽然同意挑战本身不会过期，但生成的基于时间的身份验证方法会过期（例如，OTP、电子邮件链接）。有关 k-ID 如何在用户流程中使用基于时间的身份验证的更多详细信息，请参阅 挑战。

获取可信成人电子邮件地址​

如果授予同意，父母的电子邮件地址在 /challenge/get-status 响应的 approverEmail 字段中返回。这可以由游戏存储，用于未来的客户服务案例。

有关挑战的更多信息，包括测试挑战，请参阅核心概念部分的 挑战。