会话和权限

会话和权限是 k-ID 中的核心概念，确定玩家可以在您的游戏中访问哪些功能和能力。

会话

k-ID Session 包含当前玩家和位置的权限和年龄状态集合。每个玩家都需要一个活动的 Session。游戏应该查询活动的 Session 以确定功能在游戏中是否被允许或禁止。

有关会话的详细信息，请参阅 会话。

获取会话

您可以通过两种方式检索会话：

• /session/get：通过 sessionId 或 kuid 获取会话
• /age-gate/check：作为年龄门控流程的一部分创建或更新会话

请求示例

GET /api/v1/session/get?sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187&etag=6d9d24fccd428f845b355122799948dd0a52fc5d
Authorization: Bearer your-api-key

/session/get API 通过使用 etag 参数支持条件请求。如果会话自上次请求以来没有更改，API 返回 HTTP 304（未修改），允许您避免不必要的数据传输。

响应示例

{
  "session": {
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "etag": "6d9d24fccd428f845b355122799948dd0a52fc5d",
    "jurisdiction": "US-CA",
    "kuid": "123456",
    "permissions": [
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "ai-generated-avatars"
      },
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "text-chat-private"
      }
    ],
    "allowances": [],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

权限

权限代表您游戏中可能需要父母同意或具有年龄限制的功能或能力。每个权限可以根据以下因素为玩家允许或禁止：

• 他们的年龄和司法管辖区
• 父母同意（如果需要）
• 权限在 Compliance Studio 中的配置

有关权限的详细信息，请参阅 权限。

使用权限

游戏代码应该使用每个 k-ID 权限来控制对游戏中相应功能的访问。如果权限的 enabled 字段为 true，这意味着功能可以在游戏中为玩家启用。如果 enabled 字段为 false，则必须关闭功能。

managedBy 字段指示谁可以允许或禁止此权限：

• PLAYER：玩家可以自己启用/禁用此权限
• GUARDIAN：只有可信成人可以启用/禁用此权限
• PROHIBITED：此权限在当前位置对于当前玩家永远不允许

如果功能在当前位置对于当前玩家永远不允许，无论其可信成人的同意如何，managedBy 字段包含值 PROHIBITED。在这种情况下，游戏完全从用户体验中删除禁止的功能而不是显示为关闭是合适的。

升级权限

在玩家收到具有权限的会话后，他们可能希望允许其他权限。使用 /session/upgrade API 请求其他权限。

更多信息，请参阅 权限升级。

呈现法律文档和数据通知

/session/upgrade 可以呈现更新后的法律文档和数据通知，供可信成人在同一同意时刻进行审阅和接受。在请求的 materialChange 中传递要呈现的文档：

• materialChange.termsOfServiceDocument、materialChange.privacyPolicyDocument 和 materialChange.additionalLegalLinks：要呈现的法律文档变体的已配置 ID。

当请求包含以下任一情况时，都会创建挑战，以便审阅和接受文档：

• 需要父母同意的监护人管理权限，
• materialChange 中的一个或多个法律文档，或
• 重大更改的重新同意（见下文）。

如果以上情况均不适用，则与之前完全相同，无需创建挑战即可直接授予权限。会话仍需同意的任何数据通知都会自动包含在内，接受挑战即记录对法律文档和数据通知的同意。

可信成人在批准页面上审阅确切的文档。要读取已解析的文档，请使用升级响应上的 challenge.documents 数组。每个条目都包含变体的 id、其本地化的 name、法律文档的 url，以及 isDataNotice（对于仅有名称的数据通知为 true；数据通知没有 url）。在重新同意链（priorChallengeId）中，该数组会累积先前挑战的文档，因此头部挑战始终保留完整集合。

请求带截止日期的重新同意（重大更改）

当文档发生变更且您需要可信成人在截止日期前重新接受时，在升级请求的 materialChange 中添加 acceptanceDeadline：

• materialChange.acceptanceDeadline：成人必须接受的截止时间（RFC 3339 UTC 日期时间）。可选：省略它可在没有截止日期的情况下呈现文档。设置时，它必须为将来的时间。
• materialChange.locale：重新同意电子邮件的语言区域（默认为 en）。

设置截止日期会使升级成为一种主动的、有截止日期的重新同意：挑战会携带截止日期（从 /challenge/get-status 作为 expiresAt 返回），并且会向可信成人发送指向同一批准页面的链接电子邮件。如果不设置截止日期，文档仍会在批准页面上呈现以供审阅，但不强制执行接受截止日期。

主动重新同意与被动重新同意

带有 acceptanceDeadline 的 /session/upgrade 上的 materialChange 用于与升级捆绑的主动重新同意。要发送仅通知（被动）而不限制访问的电子邮件，请改用专用的 /session/send-material-change-notice API。

使用权限升级小部件

使用 k-ID API 构建自定义 VPC 流程时，可以使用权限升级小部件来允许玩家请求需要父母同意的其他权限。小部件处理权限升级的同意工作流。

仅限监护人管理的会话

权限升级小部件仅适用于监护人管理的会话。如果玩家的会话是玩家管理的（其中 managedBy 为 "PLAYER"），则可以通过 /session/upgrade API 直接启用权限，而无需创建挑战，因此不需要小部件。

需要父母身份验证

会话权限管理小部件必须仅在父母身份验证的会话中托管。小部件不提供自己的父母身份验证，因此绝不应直接呈现给未成年人。始终确保小部件仅显示给经过身份验证的父母或可信成人。

有关权限升级的一般信息，包括何时需要它们以及它们如何工作，请参阅核心概念部分的 权限升级。

生成权限升级小部件 URL

调用 /widget/generate-manage-session-permissions-url API 创建权限升级小部件 URL。这将返回一个唯一 URL，供可信成人审查和批准其他权限。

请求示例

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

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "email": "parent@example.com"
}

请求参数

属性	说明	必需?
sessionId	会话的 ID	是
email	可信成人的电子邮件地址	是

响应示例

{
  "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.ExitReview。

如果权限升级小部件嵌入在 iframe 中，您可以监听来自小部件的窗口消息：

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // 处理小部件完成事件
  if (message.eventType === 'Widget.ExitReview') {
    // 权限升级流程完成
    console.log('Permissions upgrade completed');
    handleUpgradeCompleted();
  }
});

Webhooks（服务器端）

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

配置 webhook 端点以接收与会话相关的事件。当权限升级时，会话更改会在 Session.ChangePermissions 事件中反映。更多信息，请参阅 Webhooks。

权限升级和会话

当通过小部件升级权限时，会话会使用新权限更新。会话跟踪哪些权限已启用以及何时启用。您可以通过调用 /session/get API 检索会话以检查更新的权限。

有关权限升级如何与会话工作的更多信息，请参阅核心概念部分的 权限升级。

会话缓存

Session 应该缓存在本地或云存储中，并且可以与玩家的账户关联。k-ID 会话只有在父母更新权限、儿童或青少年"升级"到下一个年龄类别，或者被父母或玩家删除时才会更改。

虽然建议游戏在每次游戏重启时从 /session/get API 刷新会话，但这并不是明确要求的。此外，k-ID Webhooks 可用于接收 Session 更新，而不是调用 /session/get API。

会话 Webhooks

配置 webhooks 以接收与会话相关的事件：

• Session.ChangePermissions：在父母修改权限时发送
• Session.Delete：在会话被删除时发送

更多信息，请参阅 Webhooks。