跳到主要内容

最佳实践

年龄门控最佳实践​

始终检查年龄门控要求​

在收集年龄信息之前，始终使用玩家的司法管辖区调用 /age-gate/get-requirements。这确保您：

  • 仅在需要时显示年龄门控（shouldDisplay = true）
  • 仅使用该司法管辖区批准的年龄收集方法
  • 了解年龄阈值（数字同意年龄、民事年龄、最低年龄）
  • 知道是否需要年龄保证

处理所有年龄门控检查响应​

调用 /age-gate/check 时，处理所有三种可能的状态：

  • PROHIBITED：玩家低于最低年龄 - 完全阻止访问
  • CHALLENGE：玩家需要父母同意 - 创建并显示挑战
  • PASS：玩家可以继续 - 检索或创建会话

永远不要假设玩家可以在不检查响应状态的情况下继续。

VPC 和挑战最佳实践​

持久存储挑战 ID​

当从 /age-gate/check 返回 CHALLENGE 状态时，将挑战 ID 存储在本地存储或您的服务器中。这允许您：

  • 如果玩家在授予同意之前返回，恢复同意流程
  • 在后续访问时显示相同的挑战信息（二维码、OTP）
  • 使用 /challenge/get 检索挑战详细信息

使用 webhooks 获取挑战状态（推荐）​

配置 webhooks 以接收 Challenge.StateChange 事件，而不是轮询。Webhooks 提供：

  • 当授予或拒绝同意时的实时更新
  • 减少 API 调用并提高性能
  • 更可靠的状态跟踪

如果必须使用轮询，请实施适当的速率限制：

  • 对 /challenge/get-status 的调用之间至少间隔 5 秒
  • 始终检查 HTTP 429 响应并实施适当的重试逻辑
  • 设置适当的超时限制

有效通知可信成人​

创建挑战时，为可信成人提供多种完成同意的方式：

  • 电子邮件通知：如果电子邮件地址可用，调用 /challenge/send-email
  • 二维码显示：显示挑战响应中返回的二维码 URL
  • OTP 输入：显示一次性密码以供手动输入

存储来自挑战状态响应的 approverEmail 用于客户服务目的。

会话管理最佳实践​

适当缓存会话​

会话应该缓存在本地或云存储中，并与玩家的账户关联。会话只有在以下情况下才会更改：

  • 父母更新权限
  • 玩家"升级"到下一个年龄类别
  • 会话被父母或玩家删除

使用 ETags 进行高效的会话检索​

/session/get API 通过使用 etag 参数支持条件请求。包含来自您缓存的会话的 ETag：

  • 如果会话没有更改，API 返回 HTTP 304（未修改）
  • 这减少了不必要的数据传输并提高了性能
  • 游戏重启时始终刷新会话

实施会话 webhooks​

配置 webhooks 以接收与会话相关的事件：

这提供了无需轮询的实时更新，并确保您的游戏立即反映权限更改。

正确处理会话升级​

当玩家请求需要父母同意的其他权限时：

  • 使用 /session/upgrade 为新权限创建挑战
  • 使用权限升级小部件处理同意工作流
  • 通过 webhooks 或轮询监控会话更改以检测何时批准升级

权限最佳实践​

尊重权限状态​

始终检查每个权限的 enabled 和 managedBy 字段：

  • enabled: true：可以为玩家启用功能
  • enabled: false：必须关闭功能
  • managedBy: PLAYER：玩家可以自己启用/禁用
  • managedBy: GUARDIAN：只有可信成人可以启用/禁用
  • managedBy: PROHIBITED：功能永远不允许 - 完全从 UI 中删除它

正确映射权限到游戏功能​

确保每个 k-ID 权限都正确映射到游戏中相应的功能。权限应控制对以下内容的访问：

  • 年龄限制内容
  • 需要父母同意的功能
  • 数据收集能力
  • 通信功能

在 Compliance Studio 中配置权限以匹配您的游戏功能集。

安全建议​

仅服务器 API 调用​

重要

所有小部件 URL 生成端点应仅从您的服务器调用，永远不要直接从客户端代码调用。

您的 k-ID API 密钥是必须保护的秘密凭据：

  • 安全存储 API 密钥使用密钥管理器
  • 永远不要在前端 JavaScript、移动应用代码或任何面向客户的代码中暴露 API 密钥
  • 永远不要在客户端设备或客户端存储中存储 API 密钥

目标源配置​

CDK 提供在 Compliance Studio 中配置目标源的能力，以控制哪些域可以嵌入您的小部件。此设置控制内容安全策略的 frame-ancestors 指令。作为可选的安全措施，建议评估您的风险承受能力，并根据您的安全要求决定是否实施目标源限制。

配置选项：

  • 特定域：为生产使用设置确切域（例如，https://yourgame.com）
  • 通配符子域：对子域使用通配符模式（例如，https://*.yourgame.com）
  • 无限制：留空或设置为 * 以无限制嵌入（不推荐用于生产）

安全优势： 目标源防止攻击者在恶意站点上的透明 iframe 中嵌入您的合规流程，他们可以在其中覆盖其他内容并诱骗用户无意中点击验证元素。

重要

实施注意事项：

  • 为每个环境（测试/实时）配置单独的目标源
  • 在上线之前，确保为所有生产端点正确配置目标源。
  • 除非使用通配符，否则每个子域都需要自己的条目
信息

无论目标源设置如何，只有某些 k-ID 页面可以嵌入在 iframe 中（验证页面、小部件和 VPC 流程）。所有其他 k-ID 页面（家庭管理、账户设置）始终被阻止在 iframe 嵌入中。

iframe 权限​

始终在您的 iframe allow 属性中包含必要的权限：

<iframe 
  src="WIDGET_URL"
  allow="camera;payment;publickey-credentials-get;publickey-credentials-create"
  width="100%"
  height="600"
></iframe>

权限分解：

  • camera - 面部年龄估计所需（如果使用）
  • payment - 信用卡验证所需（如果使用）
  • publickey-credentials-create - AgeKey 创建所需（如果使用）
  • publickey-credentials-get - AgeKey 验证所需（如果使用）

源验证​

始终验证传入消息的源：

window.addEventListener('message', (event) => {
  // 根据环境验证源
  const validOrigins = [
    'https://family.k-id.com',        // 实时环境
    'https://family.test.k-id.com'    // 测试环境
  ];
  
  if (!validOrigins.includes(event.origin)) {
    return; // 忽略来自未授权源的消息
  }
  
  // 处理事件
  handleWidgetEvent(event.data);
});

账户系统集成​

产品上下文映射​

将 CDK 与跨多个游戏的账户系统集成时：

  • 在 Compliance Studio 中将每个游戏映射到其自己的 k-ID 产品
  • 为账户系统本身创建一个单独的 k-ID 产品以用于全局权限
  • 确保为每个产品上下文使用正确的 API 密钥
  • 在您的账户系统中存储来自会话的 kuid 以进行跨产品会话检索

多个产品的会话缓存​

在您的账户系统中按产品 ID 缓存会话：

  • 使用 k-ID 产品 ID 作为缓存键
  • 在触发新 VPC 流程之前检查现有会话
  • 如果产品已存在会话，允许玩家在没有额外同意的情况下继续

司法管辖区处理​

在进行 API 调用时始终传递正确的司法管辖区：

  • 从玩家的位置或 IP 地址确定司法管辖区
  • 使用特定于司法管辖区的年龄阈值和要求
  • 通过调用 /session/update-jurisdiction 处理游戏过程中的司法管辖区更改