最佳实践

年龄验证最佳实践

处理验证失败

实施访问年龄验证时，开发者应检查验证结果中的 failureReason 字段以正确处理失败：

欺诈活动检测：如果验证失败且 failureReason 为 fraudulent-activity-detected，不要允许该用户进行额外的验证尝试。
其他失败原因：对于所有其他失败原因（如 age-criteria-not-met 或 max-attempts-exceeded），实施速率限制以防止滥用，同时允许合法的重试尝试。允许最多每 24 小时 3 次验证尝试。这可以防止用户反复尝试绕过验证系统，同时为合法用户提供合理的重试机会

安全建议

仅服务器 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);
});

年龄验证最佳实践​

处理验证失败​

安全建议​

仅服务器 API 调用​

目标源配置​

iframe 权限​

源验证​