瀑布流

使用 k-ID 进行年龄验证是一个隐私保护型过程，允许用户在不透露个人信息的情况下证明其年龄。此方法使用瀑布流模型。

瀑布流

AgeKit+ 作为年龄检查的单点编排器，自动级联通过验证提供商的瀑布流来确认用户的年龄。实际上，对 k-ID 的一次 API 调用按顺序呈现配置的方法。例如，从电子邮件推理或面部年龄估计开始，然后根据需要回退到 ID 文档扫描或其他方法，直到用户的年龄得到验证或所有选项都用尽。这意味着开发者只需与 k-ID 的 API 集成一次，平台会在幕后处理尝试多种验证技术，组合方法以最大化成功验证的机会。

验证流程通过返回要在 iframe 或移动 Web 视图中托管的 URL 的 API 调用启动，用户在此界面中完成验证过程。可用验证方法由您在 Compliance Studio 中的产品配置确定，确保符合司法管辖区要求。

API	场景
`/age-verification/perform-access-age-verification`	在获得对功能、成熟内容或产品本身的访问之前验证用户年龄。
`/age-verification/perform-trusted-adult-verification`	执行可信成人（父母或监护人）验证。
`/age-verification/perform-age-appeal`	对于年龄验证失败但想要对决定提出上诉的用户。

年龄验证 API 在请求和响应格式方面是标准化的。

请求正文

属性	说明	必需?
`jurisdiction`	应进行年龄验证的司法管辖区	是
`criteria`	年龄验证的标准	是
`subject.email`	如果用户在任何其他上下文中使用电子邮件地址通过 k-ID 验证了其年龄，则返回原始年龄而不是要求用户再次估计或证明其年龄。	否
`subject.claimedAge`	如果用户在年龄门控中被询问其年龄，用于通知年龄估计过程	否
`subject.id`	用于跨多个验证方法报告多次失败尝试的标识符。这可以是临时会话 ID 或哈希用户 ID。	否
`options.facialAgeEstimation.minAge`	面部年龄估计结果的最小可接受年龄。这通常应设置为高于 `criteria.age`，以考虑年龄估计技术固有的方差。例如，如果您的要求是 18+，将 `minAge` 设置为 21-25 可提供置信度缓冲，减少误报。这确保通过面部年龄估计的用户更可能满足您的实际年龄要求。	否

示例：

{
  "jurisdiction": "US-CA",
  "subject": {
    "email": "user@example.com",
    "claimedAge": 23,
    "id": "3854909b-8888-4bed-9282-24b74c4a3c97"
  },
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  },
  "options": {
    "facialAgeEstimation": {
      "minAge": 21
    }
  }
}

响应正文

对年龄验证 API 的成功请求返回以下响应。

属性	说明
`id`	由年龄验证服务生成的唯一验证 ID
`url`	必须嵌入 iframe 中并呈现给用户的年龄验证 URL，供他们验证自己。

示例：

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJ..."
}

嵌入验证界面

使用返回的 URL 在您的网站或应用中创建 iframe。用户通过此界面完成验证，可用方法自动适应司法管辖区要求。

<div id="verification-container">
  <iframe 
    id="verification-widget"
    src="VERIFICATION_URL" 
    width="100%" 
    height="600"
    frameborder="0"
    allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
  </iframe>
</div>

allow 属性需要启用以下功能：

camera：面部年龄估计所需
payment：信用卡验证所需
publickey-credentials-get 和 publickey-credentials-create：基于 WebAuthn 的验证方法所需

验证结果

一旦用户成功完成年龄验证，或用户已达到最大重试次数但未成功，年龄验证结果通过客户端和服务器端渠道传递。实现应结合使用两者：客户端事件最适合控制 UI 元素，而对于数据完整性，实际结果应来自 webhook 或调用 /age-verification/get-status。

客户端（DOM 事件） - 如果响应正文中的 URL 包含在 iframe 中，它会作为窗口消息（MessageEvent）发送到父框架，具有 Verification.Result 结构。

服务器端（webhooks） - 事件以 Verification.Result 事件的形式发送到注册的 webhook。

访问窗口消息的示例：

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 使用 DOM 事件进行即时 UI 更新
    updateUI(message);
  }
};

window.addEventListener("message", handleMessage);

important

对于数据完整性，始终通过 webhook 事件或调用 /age-verification/get-status 来验证结果，而不是仅依赖 DOM 事件。DOM 事件最适合响应式 UI 更新。

窗口事件和 webhook 事件的数据元素包含以下属性。

属性	说明
`id`	这是结果的验证 ID。
`status`	指示 `PASS` 或 `FAIL` 状态，基于用户是否满足年龄标准。
`ageCategory`	指示用户在请求中指定的司法管辖区中属于的年龄类别。支持的值是 `adult`、`digital-youth` 或 `digital-minor`
`method`	指示用于验证的方法。支持的值是 `id-document`、`age-estimation`、`age-attestation`、`credit-card`、`social-security-number`
`failureReason`	验证失败的原因。支持的值是 `age-criteria-not-met`、`max-attempts-exceeded` 或 `fraudulent-activity-detected`。仅在 `status` 为 `FAIL` 时设置
`age`	返回估计或验证年龄的下限和上限，作为 `low` 和 `high`。

示例：

{
    "eventType": "Verification.Result",
    "data": {
        "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
        "status": "PASS",
        "ageCategory": "adult",
        "method": "id-document",
        "age": {
            "low": 25,
            "high": 25,
        }
    }
}

处理窗口事件：

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result" && ) {
    if (message.data.status === "PASS") {
      window.location.href = `https://www.example.com/success?verificationId=${message.data.id}`
    }
    if (message.data.status === "FAIL") {
      window.location.href = `https://www.example.com/fail?verificationId=${message.data.id}`
    }
  }
};

window.addEventListener("message", handleMessage);

验证错误

如果发生意外错误，会触发 JavaScript 事件，以便您的实现可以优雅地处理错误。

有关事件结构的详细信息，请参阅 Verification.Error。

示例消息：

{
    "eventType": "Verification.Error",
    "method": "credit-card",
    "status": "ERROR"
}

检查验证状态

除了在 JavaScript 中发送事件并通过 k-ID webhook 发送事件外，还可以查询验证的状态。这对于能够处理注册的 webhook 在一段时间内无法访问且状态事件从未发送的情况很有用。要获取验证的状态，请使用 /age-verification/get-status API。返回的数据结构与发送到 webhook 的 Verification.Result 事件数据相同。有关 webhook 事件的更多信息，请参阅 Webhooks。

限制验证尝试

每个验证请求允许用户对每个可用验证方法进行三次尝试。如果出现以下情况，验证将失败：

所有可用验证方法都已用尽，无法确定年龄
确定了年龄但低于您标准的所需阈值

当验证失败时，您可以允许用户启动新的验证尝试。但是，为了防止滥用和滥用验证系统，您应该对额外的验证尝试实施速率限制。例如，您可能将用户限制为在 24 小时内进行三次验证尝试。

使用验证请求中的 subject.id 字段来跟踪跨多个验证请求的尝试。此字段应包含用户的一致标识符（如临时会话 ID 或哈希用户 ID），允许您：

跟踪每个用户的验证尝试次数
实施基于时间的速率限制（例如，每 24 小时 3 次尝试）
防止用户通过创建新会话来绕过限制

最佳实践

在启动验证请求之前，在服务器上实施速率限制。这可以防止不必要的 API 调用，并有助于保护您的系统免受滥用。

验证方法

有关所有可用验证方法的详细信息，请参阅验证方法。

瀑布流​

请求正文​

响应正文​

嵌入验证界面​

验证结果​

验证错误​

检查验证状态​

限制验证尝试​

验证方法​

瀑布流