使用 Play Age Signals API（Beta 版）

使用 Play Age Signals API（Beta 版）即表示您同意遵守服务条款，并同意遵守所有 Google Play 开发者政策。如需请求用户的状态和年龄段，您可以在运行时从应用中调用该 API。Play Age Signals API 仅针对位于以下区域的用户返回数据：根据法律规定，Play 必须提供年龄段数据。

Play 会根据适用管辖区和地区定义的年龄段返回年龄范围。在适用管辖区和地区，API 返回的默认年龄段为 0-12 岁、13-15 岁、16-17 岁和 18 岁以上，但这些年龄段可能会根据地区要求而发生变化。

将 Play Age Signals API 集成到您的应用中

如需将 Play Age Signals API 集成到您的应用中，请将以下依赖项添加到应用的 build.gradle 文件中：

implementation 'com.google.android.play:age-signals:0.0.1'

请求年龄信号

以下示例展示了如何发出年龄信号请求：

Kotlin

// Create an instance of a manager
val ageSignalsManager =
    AgeSignalsManagerFactory.create(ApplicationProvider.getApplicationContext())

// Request an age signals check
ageSignalsManager
    .checkAgeSignals(AgeSignalsRequest.builder().build())
    .addOnSuccessListener { ageSignalsResult ->
        // Store the install ID for later...
        val installId = ageSignalsResult.installId()

        if (ageSignalsResult.userStatus() == AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_DENIED) {
          // Disallow access...
        } else {
           // Do something else if the user is SUPERVISED, VERIFIED, etc.
        }
    }

Java

// Create an instance of a manager
AgeSignalsManager ageSignalsManager =
    AgeSignalsManagerFactory.create(ApplicationProvider.getApplicationContext());

// Request an age signals check
ageSignalsManager
    .checkAgeSignals(AgeSignalsRequest.builder().build())
    .addOnSuccessListener(
        ageSignalsResult -> {
          // Store the install ID for later...
          String installId = ageSignalsResult.installId();

          if (ageSignalsResult
              .userStatus()
              .equals(AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_DENIED)) {
            // Disallow access ...
          } else {
            // Do something else if the user is SUPERVISED, VERIFIED, etc.
          }
        });

Google Play 会在设备上为每位用户存储年龄信号。当使用受监督的 Google 账号的用户进入新的年龄段时，Google Play 会在用户生日后的 2 到 8 周内自动更新该用户的缓存年龄信号。

（可选）接收自定义年龄范围

在适用管辖区和地区，该 API 返回的默认年龄段为 0-12 岁、13-15 岁、16-17 岁和 18 岁以上。这些年龄段将来可能会根据当地要求而发生变化。

或者，您也可以根据应用的最低年龄要求来自定义年龄段，只需在 Google Play 管理中心的年龄信号页面上提供应用的最低年龄要求即可。Age Signals API 会返回自定义的年龄段。 例如，如果您提供的最低年龄分别为 9 岁、15 岁和 17 岁，那么 14 岁的用户就会归入 10-15 岁的年龄段。最低年龄之间必须至少相差 2 周岁，且每年只能更改一次。

如需自定义 Age Signals API 返回的年龄范围，您可以为应用提供最低年龄值：

  1. 前往 Play 管理中心内的年龄信号页面。
  2. 在应用的最低年龄要求标签页上，输入应用的最低年龄要求（最多三个）。
  3. 点击 Save。

年龄信号响应

Play Age Signals API（Beta 版）响应包含以下字段和值。这些值可能会发生变化。如果您需要最新值，请在应用打开时请求 API 响应。您有责任使用这些信号提供适合相应年龄段的体验。

响应字段 值 说明
userStatus 已验证 用户已年满 18 周岁。Google 使用商业上合理的方法（例如由政府签发的身份证件、信用卡或人脸年龄估计）验证了用户的年龄。
受监督 用户拥有一个受监督的 Google 账号，该账号由设置其年龄的家长管理。 使用 ageLower 和 ageUpper 确定用户的年龄段。
SUPERVISED_APPROVAL_PENDING 用户拥有受监督的 Google 账号，但其监督家长尚未批准一项或多项待处理的重大变更。 使用 ageLower 和 ageUpper 确定用户的年龄段。 使用 mostRecentApprovalDate 可确定已获批准的上次重大更改。
SUPERVISED_APPROVAL_DENIED 用户拥有受监督的 Google 账号，但其监督家长拒绝批准一项或多项重大变更。 使用 ageLower 和 ageUpper 确定用户的年龄段。 使用 mostRecentApprovalDate 可确定已获批准的上次重大更改。
未知 用户在适用司法管辖区和地区未通过验证或未受到监督。这些用户可能年满 18 周岁，也可能未满 18 周岁。如需从 Google Play 获取年龄信号，请让用户访问 Play 商店以解决其状态问题。
空（空白值） 所有其他用户都会返回此值。
ageLower 0 至 18 受监督用户的年龄范围的下限（含）。 使用 ageLower 和 ageUpper 确定用户的年龄段。
空（空白值）
 userStatus 为未知或为空。
ageUpper 2 至 18 受监督用户的年龄范围的上限（含）。 使用 ageLower 和 ageUpper 确定用户的年龄段。
空（空白值） 或者 userStatus 受监督，且用户的家长证明年龄超过 18 周岁。 或者 userStatus 经过验证、未知或为空。
mostRecentApprovalDate 日期戳 已获批准的最新重大更改的 effective from 日期。安装应用时，系统会使用安装前最近一次重大更改的日期。
空（空白值） 或者 userStatus 处于监督状态，且未提交任何重大变更。 或者 userStatus 经过验证、未知或为空。
installID Play 生成的字母数字 ID。 Google Play 为受监督的用户安装分配的 ID，用于在应用审批被撤消时通知您。 查看有关撤消应用审批的文档。
空（空白值） userStatus 已验证、未知或为空。

响应示例

对于已验证的用户，您会收到以下信息：

  • userStatus 将为 AgeSignalsVerificationStatus.VERIFIED。
  • 其他响应字段将为空。

对于受监督的用户，您会收到以下信息：

  • userStatus 将为 AgeSignalsVerificationStatus.SUPERVISED。
  • ageLower 将是一个数字（例如 13）。
  • ageUpper 将是一个数字（例如 15）。
  • mostRecentApprovalDate 将是 Java 日期对象（例如 2026-01-01），或者为空（如果尚未批准任何重大变更）。
  • installID 是 Play 生成的字母数字 ID（例如 550e8400-e29b-41d4-a716-446655441111）。

对于有待处理的重大变更审批的受监督用户，您会收到以下内容：

  • userStatus 将为 AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING。
  • ageLower 将是一个数字（例如 13）。
  • ageUpper 将是一个数字（例如 15）。
  • mostRecentApprovalDate 将是 Java 日期对象（例如 2026-01-01），或者为空（如果尚未批准任何重大变更）。
  • installID 是 Play 生成的字母数字 ID（例如 550e8400-e29b-41d4-a716-446655441111）。

处理 API 错误代码

如果您的应用发出 Play Age Signals API 请求，但调用失败，则您的应用会收到一个错误代码。出现这些错误的原因有很多，例如 Play 商店应用已过时。

重试策略

当用户正在会话中时，我们建议实现一个重试策略，将尝试次数上限作为退出条件，以便尽可能避免错误干扰用户体验。

错误代码的数值 错误代码 说明 可重试
-1 API_NOT_AVAILABLE Play Age Signals API 不可用。设备上安装的 Play 商店应用版本可能太低。

可能的解决方法
  • 让用户更新 Play 商店。
 是
-2 PLAY_STORE_NOT_FOUND 在设备上未找到 Play 商店应用。 让用户安装或启用 Play 商店。 是
-3 NETWORK_ERROR 未找到可用网络。 让用户检查网络连接。 是
-4 PLAY_SERVICES_NOT_FOUND Play 服务不可用或版本太低。 让用户安装、更新或启用 Play 服务。 是
-5 CANNOT_BIND_TO_SERVICE 绑定到 Play 商店中的服务时失败。这可能是因为设备上安装的 Play 商店版本太低，或者设备内存过载。让用户更新 Play 商店应用。 使用指数退避算法重试。 是
-6 PLAY_STORE_VERSION_OUTDATED Play 商店应用需要更新。 让用户更新 Play 商店应用。 是
-7 PLAY_SERVICES_VERSION_OUTDATED Play 服务需要更新。 让用户更新 Play 服务。 是
-8 CLIENT_TRANSIENT_ERROR 客户端设备出现暂时性错误。 实现重试策略，并将尝试次数上限作为退出条件。如果问题仍未解决，请让用户稍后再试。 是
-9 APP_NOT_OWNED 该应用并非由 Google Play 安装。 让用户从 Google Play 获取您的应用。 否
-100 INTERNAL_ERROR 未知内部错误。 实现重试策略，并将尝试次数上限作为退出条件。如果问题仍未解决，请让用户稍后再试。 如果该测试一直失败，请与 Google Play 开发者支持团队联系，并在主题中添加 Play Age Signals API，同时尽可能详细地提供技术信息（例如 bug 报告）。 否
上一页
概览
下一页
通知重大变更