会话和权限

会话和权限是 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 请求其他权限。

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

使用权限升级小部件

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

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

生成权限升级小部件 URL

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

请求示例

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

{
  "challengeId": "ae6d4729-af32-42ea-8ef2-ff46c7664802",
  "email": "parent@example.com"
}

请求参数

属性	说明	必需?
challengeId	由 /session/upgrade 创建的 VPC 挑战的 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。