嵌入式流程

CDK 提供一个端到端小部件，在单个界面中处理完整的可验证父母同意 (VPC) 流程，在一个无缝体验中涵盖年龄门控、VPC、数据通知、权限和偏好设置。

什么是端到端小部件？

端到端小部件是一个全面的解决方案，在单个界面中处理完整的合规流程，在一个无缝体验中涵盖年龄门控、VPC、数据通知、权限和偏好设置。此小部件可以由父母在孩子的设备上或他们自己的设备上使用，为同意过程提供最大的灵活性。

生成小部件 URL

调用 /widget/generate-e2e-url API 创建处理完整 VPC 流程的端到端小部件 URL。这将返回一个唯一 URL，供用户完成年龄收集和父母同意过程。

请求示例

POST /api/v1/widget/generate-e2e-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA"
}

配置标志

可选的 flags 参数允许您自定义要跳过的流程部分：

• skipDataNotices：跳过数据通知和同意收集
• skipVerification：跳过验证步骤
• skipPermissions：跳过权限管理
• skipPreferences：跳过偏好设置

传递平台年龄信号（可选）

如果您的游戏已有来自平台的年龄数据（Apple iOS、Google Play、Xbox、Meta Horizon 或先前的 k-ID 验证），请将其作为 platformAgeSignal 包含在请求正文中。小部件会将该信号转发给底层的年龄门控检查，因此可以在已验证信号表明是成人时跳过年龄门控、无需额外验证步骤即可满足已验证年龄权限，并检测信号与玩家自报年龄之间的冲突。

POST /api/v1/widget/generate-e2e-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}

有关支持的平台和字段形式，请参阅平台年龄信号。

响应示例

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

嵌入小部件

使用返回的 URL 在您的网站或应用中创建 iframe。用户通过此界面完成年龄收集和可信成人同意过程，可用方法自动适应司法管辖区要求。

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

处理事件

小部件发出您可以监听的 JavaScript 事件：

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

关闭 UI

要确定何时关闭小部件 UI，请监听 Widget.ExitReview 事件。当用户单击"完成"按钮时会发出此事件，表示流程已完成，应关闭或隐藏 iframe。

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  if (message.eventType === 'Widget.AgeGate.Challenge') {
    if (message.data.status === 'PASS') {
      // 父母批准同意 - 授予访问权限
      console.log('Consent approved:', message.data.sessionId);
      grantAccess(message.data.sessionId);
    } else if (message.data.status === 'FAIL') {
      // 父母拒绝同意 - 限制访问
      console.log('Consent denied');
      restrictAccess();
    }
  }
  
  if (message.eventType === 'Widget.ExitReview') {
    // 用户单击"完成"时关闭小部件 UI
    closeWidget();
  }
});

小部件处理的内容

小部件自动处理：

• 年龄收集：符合司法管辖区要求的年龄收集方法
• 数据通知：根据 Compliance Studio 中的产品配置接受的数据通知
• 权限：根据 Compliance Studio 中的产品配置管理的权限
• 父母同意挑战：如果确定用户是未成年人，则会创建挑战以供可信成人批准
• Automatic age assurance：如果产品在该司法管辖区启用了 Automatic age assurance，那些声明年龄足以跳过父母同意的玩家将被要求在小部件内证明所声明的年龄（面部年龄估计或 ID 文件），然后才能签发会话。

具体流程取决于司法管辖区和您在 Compliance Studio 中的产品配置。

启用 Automatic age assurance 后的会话创建时机

当 Automatic age assurance 在端到端小部件内触发时，会话是在玩家通过验证之后创建，而不是在年龄门控之后立即创建。流程完成后仍会触发 Widget.AgeGate.Result 事件，并在 PASS 时包含 sessionId。在该事件到达之前，请将流程视为正在进行中。

有关实施 VPC 的更多信息，请参阅 快速入门指南。