嵌入式流程

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

不推荐用于移动端

端到端和年龄门控小部件不推荐用于移动应用。在移动端，请使用自定义工作流并原生构建年龄门控和同意 UX 元素，遵循 CDK UX 指南。

移动端唯一支持的 Web 嵌入是 k-ID API 返回的年龄验证和年龄保证 URL。有关具体端点和挑战类型，请参阅移动应用指南。

什么是端到端小部件？

端到端小部件是一个全面的解决方案，在单个界面中处理完整的合规流程，在一个无缝体验中涵盖年龄门控、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 是一个托管的网页。请在适合您应用程序的环境中打开它：

Web 应用：嵌入到 iframe 中（参见下方示例）、在弹出窗口中打开，或整页重定向。
移动应用（不推荐）：端到端小部件不推荐用于移动端。请使用自定义工作流原生构建年龄门控和同意 UX，并仅嵌入年龄验证 URL。受支持的方法请参阅移动应用快速入门指南。
主机游戏（Switch、PlayStation、Xbox）：主机浏览器通常受限或不存在。将小部件 URL 显示为二维码，让玩家在配对的移动设备上完成流程。由于移动设备的重定向无法返回到主机，请通过 webhook 加 /session/get 轮询来接收结果。

小部件内可用的方法会自动适应司法管辖区要求，与托管环境无关。

Web 示例

<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>

对于移动环境，调用 /widget/generate-e2e-url 时传递 options.redirectUrl，并在应用中处理回调。端到端示例请参阅移动应用快速入门指南。

处理事件

DOM 事件可达的位置

下方的 JavaScript 事件（Widget.AgeGate.Result、Widget.AgeGate.Challenge、Widget.ExitReview）通过 postMessage 传递。要接收它们，宿主需要对小部件的 window 有一个活跃的 JavaScript 监听器。这包括 iframe 宿主、通过 window.open 打开的弹出窗口，以及带 JS 桥的移动端 WebView / WKWebView（参阅移动应用快速入门）。系统浏览器组件（ASWebAuthenticationSession、SFSafariViewController、Chrome Custom Tabs）和整页顶层重定向不暴露监听器，因此通过 redirectUrl 回调接收结果，并使用 /session/get 或 webhooks 在服务器端确认。

小部件发出您可以监听的 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 的更多信息，请参阅快速入门指南。

什么是端到端小部件？​

生成小部件 URL​

请求示例​

配置标志​

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

响应示例​

展示小部件 URL​

Web 示例​

处理事件​

小部件处理的内容​