最佳实践

年龄验证最佳实践

处理验证失败

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

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

安全建议

仅后端API调用

重要：所有组件URL生成端点应仅从您的后端服务器调用，切勿直接从客户端代码调用。您的k-ID API密钥是必须保护的秘密凭据：

使用密钥管理器安全存储API密钥
切勿在前端JavaScript、移动应用程序代码或任何面向客户的代码中暴露API密钥
切勿在客户端设备或客户端存储中存储API密钥

目标来源配置

在合规工作室中配置目标来源以控制哪些域可以嵌入您的组件。此设置控制内容安全策略的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;autoplay;payment;publickey-credentials-get;publickey-credentials-create"
  width="100%"
  height="600"
></iframe>

权限分解：

camera - 面部年龄估计所需
autoplay - 面部年龄估计使用（可选，防止控制台警告）
payment - 信用卡验证可选（启用浏览器支付API）
publickey-credentials-get/create - 年龄密钥验证所需

来源验证

始终验证传入消息的来源：

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权限​

来源验证​