跳到主要内容

年龄门控

年龄门控是一种机制，用于在允许访问年龄限制内容、功能或服务之前收集和验证用户的年龄。k-ID API 提供用于管理年龄门控和根据玩家的年龄和司法管辖区确定需要采取哪些操作的端点。

正在构建自定义年龄门控 UI？

有关年龄滑块、日期选择器、同意流程和无障碍访问的设计建议，请参阅 UX 指南。

获取年龄门控要求​

使用玩家的司法管辖区调用 /age-gate/get-requirements 以确定：

  • 是否应显示年龄门控（shouldDisplay）
  • 批准了哪些年龄收集方法（approvedAgeCollectionMethods）
  • 年龄阈值：
    • digitalConsentAge：玩家可以提供数字同意的最低年龄
    • civilAge：玩家被视为合法成年人的民事/合同年龄
    • minimumAge：访问平台/游戏所需的最低年龄
  • 是否需要年龄保证（ageAssuranceRequired）

请求示例​

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA
Authorization: Bearer your-api-key

响应示例​

{
  "shouldDisplay": true,
  "ageAssuranceRequired": true,
  "digitalConsentAge": 13,
  "civilAge": 18,
  "minimumAge": 0,
  "approvedAgeCollectionMethods": [
    "date-of-birth",
    "age-slider",
    "platform-account"
  ]
}

包含平台年龄信号​

如果您的游戏拥有平台报告的年龄信号（Apple iOS、Google Play、Xbox、Meta Horizon 或 k-ID），请将其作为查询参数包含进来：platformName、platformAgeLow、platformAgeHigh、platformCategory、platformDeclarationType 和 platformVerificationId。k-ID 会在您收集任何输入之前将该信号纳入 shouldDisplay 和 ageAssuranceRequired 的判断 — 已验证的成人信号可以让您完全跳过年龄门控并立即满足已验证年龄权限。有关支持的平台和字段形式的完整列表，请参阅平台年龄信号。

GET /api/v1/age-gate/get-requirements?jurisdiction=US-CA&platformName=apple-ios&platformAgeLow=18&platformAgeHigh=25&platformDeclarationType=governmentIDChecked
Authorization: Bearer your-api-key

检查年龄以访问​

收集玩家的年龄后，使用出生日期和司法管辖区调用 /age-gate/check 以确定下一步：

  • PROHIBITED：玩家的年龄低于游戏的最低年龄。应该阻止玩家继续。
  • CHALLENGE：玩家必须先完成挑战才能创建会话。检查 challenge.type 以确定返回的是哪种挑战：
    • CHALLENGE_PARENTAL_CONSENT：声明的年龄太小，玩家无法在没有父母同意的情况下继续。可信成人必须批准后玩家才能获得会话。
    • CHALLENGE_AGE_GATE_AGE_ASSURANCE：声明的年龄足以让玩家在没有父母同意的情况下继续，但产品启用了 Automatic age assurance，玩家必须证明所声明的年龄（通常通过面部扫描或 ID 文件）后才能签发会话。
  • PASS：玩家可以继续进入游戏，响应中会返回会话。

请求示例​

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2015-04-15"
}

CHALLENGE 响应示例​

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

PASS 响应示例​

{
  "status": "PASS",
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "jurisdiction": "US-CA",
    "permissions": [...],
    "status": "ACTIVE"
  }
}

包含平台年龄信号​

您可以在请求正文中包含 platformAgeSignal 对象，可单独使用或与 dateOfBirth/age/kuid 一起使用。已验证信号无需额外验证步骤即可满足已验证年龄权限，并在会话上记录 ageVerification；未验证信号仍会用于年龄冲突检测和保守的年龄解析。有关支持的平台和已验证声明类型，请参阅平台年龄信号。

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "dateOfBirth": "2005-04-15",
  "platformAgeSignal": {
    "name": "apple-ios",
    "ageLow": 18,
    "ageHigh": 25,
    "declarationType": "governmentIDChecked"
  }
}

Automatic age assurance​

Automatic age assurance 是一项可选的产品配置，用于验证那些声明年龄足以跳过父母同意的玩家。启用后，k-ID 会拦截原本会返回 PASS 的响应，转而返回 CHALLENGE_AGE_GATE_AGE_ASSURANCE 挑战。玩家自己完成面部年龄估计或 ID 文件验证（不涉及可信成人），验证通过后 k-ID 创建会话。

启用此功能​

启用 Automatic age assurance 是一个两步过程：

  1. 必须由 k-ID 授予组织级别设置（allowAutomaticAgeAssurance）。此设置默认关闭，只能由 k-ID 切换。请联系 k-ID 支持以为您的组织启用此功能。
  2. 设置启用后，产品管理员可以在 Compliance Studio 中通过产品的引擎覆盖按司法管辖区开启或关闭 Automatic age assurance。

触发条件​

满足以下所有条件时，/age-gate/check 会返回 CHALLENGE_AGE_GATE_AGE_ASSURANCE 挑战：

  1. 目标司法管辖区的产品已启用 Automatic age assurance。
  2. 玩家声明的年龄达到或超过该年龄阈值，即玩家原本可以无需父母同意即可访问产品的年龄。该值通常是司法管辖区的数字同意年龄，但可能因产品上配置了更高的 minimum-age 或必要权限阈值而被提高。
  3. 请求中未提供达到或超过数字同意年龄的可信 平台年龄信号。已验证的平台信号（例如带有 declarationType: governmentIDChecked 的 apple-ios）已经提供了足够的保证，将绕过此挑战。

对于原本需要父母同意的声明，仍然使用现有的 CHALLENGE_PARENTAL_CONSENT 流程；Automatic age assurance 不会改变父母同意的路径。

CHALLENGE_AGE_GATE_AGE_ASSURANCE 响应示例​

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "CHALLENGE_AGE_GATE_AGE_ASSURANCE",
    "url": "https://family.k-id.com/age-gate/verify?token=..."
  }
}

与 CHALLENGE_PARENTAL_CONSENT 不同，响应中不包含 oneTimePassword。url 指向自助验证页面而不是可信成人同意门户：完成验证的是玩家本人，因此 URL 携带签名令牌，可以直接嵌入为 iframe。

处理挑战​

  1. 检测挑战类型，将 challenge.url 嵌入到带有 allow="camera;payment;publickey-credentials-get;publickey-credentials-create" 的 iframe 中。
  2. 监听 iframe 发出的 Verification.Result DOM 消息以获得响应式 UI 更新（参见 Verification.Result）。
  3. 通过 Challenge.StateChange Webhook 或轮询 /challenge/get-status 在服务端确认结果。在 PASS 时，data.sessionId 包含新创建的会话。
  4. 使用 sessionId 调用 /session/get 以检索玩家的完整权限。

有关代码示例的演练，请参阅自定义年龄门控快速入门指南中的 处理自动年龄保证挑战。

使用平台年龄类别 API​

某些平台提供返回年龄类别而非特定年龄或出生日期的 API。例如，Meta Horizon 提供了一个 GetAgeCategory API，它返回 CH（儿童，10-12 岁）、TN（青少年，13-17 岁）或 AD（成人，18 岁以上）等类别。

直接传递信号

对于大多数集成，您可以跳过转换步骤，将 platformAgeSignal 直接发送到 /age-gate/check（并作为查询参数发送到 /age-gate/get-requirements）。k-ID 会在服务端处理类别到年龄范围的转换，对已验证信号考虑声明类型，并在一次调用中运行年龄冲突检测。请参阅平台年龄信号。当您需要预先获取年龄范围以驱动自己的 UI 时，下面的转换端点仍然有用。

使用平台的年龄类别 API 时，您需要将类别转换为玩家司法管辖区的年龄范围，然后在 k-ID 的年龄门控系统中使用该年龄范围。

示例：使用 Meta Horizon 的 GetAgeCategory API​

以下是如何将 Meta Horizon 的年龄类别 API 与 k-ID 集成的完整示例：

  1. 从 Meta Horizon 获取年龄类别
// Meta Horizon Unity SDK 示例
var ageCategory = PlatformService.GetAgeCategory();
// 返回: "CH"（儿童，10-12 岁）、"TN"（青少年，13-17 岁）或 "AD"（成人，18 岁以上）
  1. 将类别转换为年龄范围
POST /api/v1/age-gate/get-platform-age-range
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "platform": {
    "name": "meta-horizon",
    "category": "TN"
  }
}

响应：

{
  "ageLow": 13,
  "ageHigh": 17
}
  1. 在年龄门控检查中使用最低年龄

使用 ageLow 值（在此示例中为 13）作为调用 /age-gate/check 时的 age 参数：

POST /api/v1/age-gate/check
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "age": 13
}

这确保了平台的已验证年龄类别能够正确转换为可在 k-ID 的年龄门控系统中使用的特定年龄值，同时保持符合司法管辖区特定要求。

出生日期格式​

有关出生日期格式和要求的信息，请参阅核心概念部分的 年龄门控。

默认权限​

如果 /age-gate/get-requirements 响应 shouldDisplay = false，则不应显示年龄门控，玩家的出生日期未定义。在这种情况下，游戏仍然通过调用 /age-gate/get-default-permissions 为司法管辖区检索默认权限来创建 Session，这意味着权限在此司法管辖区中不因年龄而异。游戏中的某些功能可能基于司法管辖区对所有年龄受众都被禁止，因此游戏仍应查询 Session 权限以检查是否可以启用功能。