数据通知

使用 k-ID API 构建自定义 VPC 流程时，可以使用数据通知小部件来显示产品数据通知并收集用户同意。小部件显示符合司法管辖区要求的披露并处理同意接受工作流。

有关数据通知的一般信息，包括何时需要它们以及存储哪些数据，请参阅核心概念部分的 数据通知。

生成数据通知小部件 URL

调用 /widget/generate-direct-notices-url API 创建数据通知小部件 URL。这将返回一个唯一 URL，供用户查看和接受数据通知。

请求示例

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

{
  "jurisdiction": "US-CA",
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
}

请求参数

属性	说明	必需?
jurisdiction	应显示数据通知的司法管辖区	是
sessionId	玩家的会话 ID（如果可用）	否

响应示例

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

嵌入小部件

使用返回的 URL 在您的网站或应用中创建 iframe。用户通过此界面查看数据通知并提供同意：

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

接收同意结果

数据通知同意作为会话的一部分进行跟踪。当接受数据通知时，同意会记录在会话中。您可以通过调用 /session/get API 在会话中检查数据通知同意状态。

对于实时更新，您还可以监听与会话相关的事件：

JavaScript 事件（客户端）

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

如果数据通知小部件嵌入在 iframe 中，您可以监听来自小部件的窗口消息：

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // 处理小部件完成事件
  if (message.eventType === 'Widget.DataNotices.ConsentApproved') {
    // 数据通知已被接受
    console.log('Data notices accepted:', message.data.jurisdiction);
    handleConsentAccepted();
  }
});

事件示例：

{
  "eventType": "Widget.DataNotices.ConsentApproved",
  "data": {
    "jurisdiction": "US"
  }
}

Webhooks（服务器端）

有关 webhook 事件结构的详细信息，请参阅 Session.ChangePermissions。

配置 webhook 端点以接收与会话相关的事件。当数据通知同意更新时，会话更改会在 Session.ChangePermissions 事件中反映。更多信息，请参阅 Webhooks。

数据通知和会话

创建会话时，数据通知同意包含在会话中。会话跟踪哪些数据通知已被接受以及何时被接受。您可以通过调用 /session/get API 检索会话以检查数据通知同意状态。

有关数据通知如何与会话工作的更多信息，请参阅核心概念部分的 数据通知。