跳到主要内容

会话

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

什么是会话？​

k-ID Session 是一个长期存在的对象，描述玩家在给定司法管辖区中在游戏中的权限。无论年龄如何，每个玩家都会获得一个长期存在的 k-ID Session，这是访问游戏所必需的。会话包含玩家在其玩游戏的司法管辖区中的权限。

对于儿童或青少年，会话可以由可信成人添加或删除权限，或由于生日而导致的年龄变化来修改。会话通常由游戏缓存在本地或云存储中。如果游戏实现了玩家账户，会话也可以与游戏中玩家的身份关联。

会话生命周期​

k-ID Session 不会自动过期。它设计为缓存在与玩家关联的本地或云存储中。对于儿童和青少年，如果父母使用 Family Connect 添加或删除权限，或者玩家过生日并在建立会话的司法管辖区中"升级"到新的年龄类别，会话可能会发生变化。

一旦玩家被可信成人授予访问权限，他们每个产品只有一个会话。当权限发生变化时（无论是通过父母修改、年龄升级事件还是权限升级），相同的会话 ID 会使用新权限进行更新。不会创建新会话；现有会话反映玩家访问的当前状态。但是，如果会话被撤销并且可信成人再次完成同意流程，将创建一个具有新会话 ID 的新会话。

由于 Session 设计为缓存，应该在每次游戏启动时使用 /session/get API 刷新它以获取已进行的任何更改。

会话结构​

会话包含：

  • sessionId：会话的唯一标识符
  • jurisdiction：创建会话的司法管辖区
  • dateOfBirth：玩家的出生日期（如果已收集）
  • ageStatus：玩家的年龄状态（DIGITAL_MINOR、DIGITAL_YOUTH 或 LEGAL_ADULT）
  • permissions：具有启用/关闭状态的权限数组
  • kuid：k-ID 用户 ID（如果玩家已通过 VPC）
  • status：会话状态（始终为 ACTIVE）
  • etag：用于缓存验证的实体标签

会话示例：

{
  "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"
      }
    ],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

获取会话​

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

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

缓存会话​

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

虽然建议游戏在每次游戏重启时从 /session/get API 刷新会话，但这并不是明确要求的。此外，k-ID Webhooks 可用于接收 Session 更新，而不是调用 /session/get API。如果 k-ID API 出现问题，刷新也可以推迟到以后。缓存的会话可用于管理权限，而无需连接到 k-ID API，同时解决任何问题。

会话和玩家身份​

k-ID Session 可以被认为与玩家的 ID 强关联。如果游戏使用 ID 系统，Session 本身可以完全存储为 JSON 文档，存储与玩家的账户关联。

跨设备会话​

在本地存储中缓存 Session 对象时，同一玩家的多个设备的本地存储中可以存在不同的会话。如果玩家在新设备上玩游戏，年龄门控会显示给玩家，如果之前需要，他们必须再次寻求同意。

为了避免必须多次请求同意，k-ID 会话可以存储在与玩家账户关联的云存储中，并在玩家在任何设备上登录时检索。在这种情况下，即使跨设备，玩家也只有一个 Session。

会话 Webhooks​

在 Compliance Studio 中，您可以注册 Webhook 以接收来自 k-ID 的事件。这避免了需要调用 /session/get 来检索 k-ID 会话的罕见更改，除非玩家_升级_。

以下 webhook 事件与会话相关：

年龄升级更改不会触发 Webhook

当玩家年龄升级并且权限发生变化时（例如，权限变为玩家管理），k-ID 不会发送 Webhook 通知。您必须使用会话比较来检测这些更改。有关实现指导，请参阅管理会话和权限。

会话删除​

当父母通过 Family Connect 撤销对您产品的访问权限时，会话将被删除。使用 /session/get 查询已删除的会话时，API 返回 HTTP 400，错误代码为 NOT_FOUND。已删除的会话不会由 API 返回——它们看起来好像从未存在过。这是有意的：一旦会话被删除，应该将其视为不再存在。

从您的集成中删除会话​

您的集成也可以使用 /session/delete 直接删除会话。默认情况下这是软删除：会话被撤销且无法再查询，但记录本身会被保留。将 hardDelete 设置为 true 则会永久删除会话及其中包含的同意记录。此操作无法撤销，且仅对明确启用了硬删除的开发者可用。请将其用于处理真正的删除请求（例如合规性删除请求），而不是作为默认删除的加强版。

如果会话所属的产品被配置为其他产品依赖的必需产品，删除其会话可能使依赖产品的会话失去所依赖的同意基础。可选的 essentialDependencies 字段用于控制替代行为，在软删除和硬删除两种路径上均有效：

  • **ignore（或省略该字段）**仅删除指定的会话，与该端点一贯的行为完全一致。省略该字段将保留现有行为，并且永远如此。
  • block 在玩家仍持有依赖此产品的活跃产品时，以 ESSENTIAL_DEPENDENTS_EXIST 拒绝删除，并列出依赖产品的 ID。当您希望 API 保护您避免孤立依赖产品时使用。
  • cascade 先删除依赖的会话（每个会话都有自己的 Session.Delete Webhook 通知），然后删除指定的会话。由于它会删除您未指定的会话，此模式仅对明确启用了此功能的开发者可用，并且需要服务器端 API 密钥而非客户端访问令牌。

只有活跃的依赖产品才会被计入（会话已被撤销的依赖产品不会阻止删除），跨开发者账户的依赖关系会被拒绝而不会级联删除。

更多信息，请参阅 Webhooks。