平台信号详情

本页是平台年龄信号的面向实现的配套文档。当您需要精确的字段形式、端点行为以及可直接映射到客户端或服务器端集成的示例时，请使用本页。

选择正确的信号形式

平台	原生信号类型	发送给 k-ID 的内容	是否验证年龄要求？	备注
Apple iOS	数字年龄范围	ageLow、ageHigh，可选 declarationType	是，针对已验证声明类型	不发送 category
Google Play	数字年龄范围	ageLow、ageHigh，可选 declarationType	是，针对已验证声明类型	不发送 category
Xbox	类别	category	否	k-ID 使用玩家的司法管辖区解析类别
Meta Horizon	类别	category	否	k-ID 使用玩家的司法管辖区解析类别
k-ID	先前验证	verificationId，加上可选的 category 或范围	是，如果验证有效	declarationType 在服务器端解析

提示

如果平台已给您 ageLow 和 ageHigh，请直接发送这些值。仅对基于类别的平台使用 POST /age-gate/get-platform-age-range。

平台特定集成指南

Apple iOS

如何获取信号： 使用 Age Range Service 获取玩家的年龄范围和声明类型。

发送给 k-ID 的内容： name、ageLow、ageHigh，以及可选的 declarationType。

已验证声明类型： paymentChecked、governmentIDChecked、guardianPaymentChecked、guardianGovernmentIDChecked

{
  "name": "apple-ios",
  "ageLow": 18,
  "ageHigh": 25,
  "declarationType": "governmentIDChecked"
}

Google Play

如何获取信号： 使用 Play Age Signals API 获取玩家的年龄范围和 userStatus。

发送给 k-ID 的内容： name、ageLow、ageHigh，以及可选的 declarationType。

已验证声明类型： VERIFIED、SUPERVISED

{
  "name": "google-play",
  "ageLow": 13,
  "ageHigh": 17,
  "declarationType": "VERIFIED"
}

Xbox

如何获取信号： 使用 XR-014 和 XUserGetAgeGroup 获取玩家的年龄组。

发送给 k-ID 的内容： name 和 category。

接受的类别： child、teen、adult

k-ID 如何解释它们：

• child = [0, digitalConsentAge - 1]
• teen = [digitalConsentAge, civilAge - 1]
• adult = [civilAge, 100]

Xbox 信号不被视为已验证年龄权限的有效验证。

{
  "name": "xbox",
  "category": "adult"
}

Meta Horizon

如何获取信号： 使用 Get Age Category API 获取 CH、TN 或 AD。

发送给 k-ID 的内容： name 和 category。

接受的类别： CH、TN、AD

k-ID 如何解释它们：

• CH = [10, digitalConsentAge - 1]，最低年龄为 10
• TN = [digitalConsentAge, civilAge - 1]
• AD = [civilAge, 100]

对于典型的巴西配置，结果为 CH=10-12、TN=13-17、AD=18+。

Meta Horizon 信号不被视为已验证年龄权限的有效验证。

{
  "name": "meta-horizon",
  "category": "TN"
}

k-ID

如何获取信号： 使用先前完成的 k-ID 验证并传入其 verificationId。

发送给 k-ID 的内容： name: "k-id" 和 verificationId。如果您的流程需要，也可以发送 category 或 ageLow 和 ageHigh，但信号是否被视为已验证取决于验证查询结果。

服务器端验证检查： 仅当验证满足以下条件时，信号才被视为已验证：

1. 存在
2. 状态为 PASS
3. 属于请求产品的同一组织

对于 k-id 信号，调用方提供的 declarationType 值将被忽略。

{
  "name": "k-id",
  "category": "adult",
  "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
}

备注

verificationId 在一个组织内的每个产品中仅限于一个活跃会话。同一验证可以在同一组织的不同产品中重用，但不能被同一产品中的多个活跃会话使用。

API 参考

以下六个端点与平台年龄信号集成最相关。每个条目描述何时以及为何调用它。有关完整的请求和响应模式，请点击链接查看 API 参考。

GET /age-gate/get-requirements

在显示年龄门控之前调用。将平台信号字段作为查询参数传入（platformName、platformAgeLow、platformAgeHigh、platformCategory、platformDeclarationType、platformVerificationId），让 k-ID 在您收集输入之前就将信号纳入考量。

需要处理的关键响应字段：

• shouldDisplay：当已验证平台信号证明玩家是成人时为 false；如果为 false，跳过年龄门控 UI
• ageAssuranceRequired：仅当每个已验证年龄权限都已由信号满足时为 false
• permissions：列出具有 verifiedAgeThreshold 的权限；即使都已满足也很有用

GET /age-gate/get-default-permissions

在不创建会话的情况下预览权限状态时调用。在完整年龄门控流程运行之前，可用于检查已验证信号是否会立即满足阈值权限。

• 具有 verifiedAgeThreshold 的权限默认为 enabled: false
• ageLow >= threshold 的已验证信号将这些权限设置为 enabled: true
• 对于 k-id 信号，声明类型从 platformVerificationId 在服务器端解析

GET /session/get

在 check、VPC 或年龄保证挑战后刷新会话。当已验证平台信号（或已完成的年龄保证）已记录在会话上时，响应包含 ageVerification 对象。检查 ageVerification.platformName 和 ageVerification.declarationType 以了解验证来源。

POST /age-gate/check

创建或更新会话。在请求正文中传入 platformAgeSignal，可以单独使用，也可以与 dateOfBirth、age 或 kuid 一起使用。当两者都存在时，k-ID 使用更保守的年龄。

与平台信号相关的可能结果：

• 已验证信号 + 年龄满足阈值： 会话包含 ageVerification，权限为 enabled: true
• 信号存在但未验证： 会话创建时不含 ageVerification；高风险权限之后需要年龄保证
• 玩家年龄低于阈值： 权限为 managedBy: PROHIBITED；适用年龄保证恢复流程
• 年龄冲突： 当启用年龄冲突检测且平台信号表明比玩家自报年龄类别更小时，返回 400 AGE_CONFLICT

POST /age-gate/get-platform-age-range

将平台类别字符串转换为给定司法管辖区的具体 ageLow/ageHigh 对。仅用于基于类别的平台（Xbox、Meta Horizon、k-ID）。如果平台已给您数字范围，请跳过此调用直接发送值。

POST /session/upgrade

为玩家的现有会话请求额外权限。这是决定高风险权限是否可以立即解锁或需要先进行年龄保证挑战的端点。

返回的挑战类型取决于请求的内容：

场景	返回的 challenge.type
权限为 PLAYER 管理	无挑战：权限立即启用
权限为 GUARDIAN 管理	CHALLENGE_SESSION_UPGRADE（可信成人同意）
权限具有 verifiedAgeThreshold 且会话无 ageVerification	CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE（玩家必须验证年龄）
权限具有 verifiedAgeThreshold 且会话已有满足阈值的 ageVerification	无挑战：权限立即启用

关键约束： 单次升级请求中的所有权限必须是同一类型。在一次调用中混合有 verifiedAgeThreshold 和没有 verifiedAgeThreshold 的权限将返回 400: "Can't mix permissions with and without verifiedAgeThreshold"。

示例：请求高风险权限（触发年龄保证）：

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

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ]
}

示例：传入来自已完成年龄申诉的 k-ID 信号，直接满足阈值而不创建新挑战：

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

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "platformAgeSignal": {
    "name": "k-id",
    "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
  }
}

当返回 CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE 挑战时，将玩家引导至 challenge.url，通过 AgeKit+ 完成年龄验证。挑战通过后，检索更新的会话：权限现在为 enabled: true，会话上有 ageVerification 对象。

验证和边缘情况

输入验证

场景	结果
缺少 name 的 platformAgeSignal	400: "Platform name must be provided"
未知平台名称	400: "Unknown platform name"
apple-ios 或 google-play 带有 category	400: "Platform must have age range specified"
同时提供 category 和 ageLow/ageHigh	400: "Provide either category or ageLow and ageHigh, not both"
仅提供 ageLow 而没有 ageHigh（或反之）	400: "ageLow and ageHigh must both be provided"
ageLow 大于 ageHigh	400: 无效范围
session/upgrade 中混合阈值和非阈值权限	400: "Can't mix permissions with and without verifiedAgeThreshold"

年龄冲突矩阵

当主要年龄和平台信号都存在时：

平台年龄类别 \ 主要年龄类别	主要：未成年人	主要：青少年	主要：成人
平台：未成年人	无冲突	冲突	冲突
平台：青少年	无冲突	无冲突	冲突
平台：成人	无冲突	无冲突	无冲突

仅当平台显示玩家比自报年龄类别更小时才会发生冲突。

k-id 信号安全规则

• declarationType 始终从 verificationId 在服务器端解析
• 调用方提供的 declarationType 被忽略
• 验证必须为 PASS
• 验证必须属于请求产品的同一组织
• 没有有效 verificationId 时，k-id 信号被视为未验证

保守默认值

• 如果 shouldDisplay 为 false 且您没有可发送的平台信号，请以 age: 1 调用 POST /age-gate/check
• 如果平台信号和主要年龄不一致但不冲突，k-ID 使用较低的年龄
• 已验证年龄权限默认为 enabled: false，直到实际满足为止