使用 Play Age Signals API（Beta 版）

使用 Play Age Signals API（Beta 版）即表示您同意遵守服务条款，并同意遵守所有 Google Play 开发者政策。如需请求用户的状态和年龄段，您可以在运行时从应用中调用该 API。仅当用户位于 Google Play 须依法律要求提供年龄类别数据的地区时，Play Age Signals API 才会返回其数据。

Play 会根据适用管辖区和地区定义的年龄段返回年龄段。在适用管辖区和地区，API 返回的默认年龄段为 0-12 岁、13-15 岁、16-17 岁和年满 18 周岁，但您可能会收到自定义年龄段。Google Play 会在用户生日后的 2 到 8 周内自动更新用户的缓存年龄信号。

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

Play Age Signals API 支持搭载 Android 6.0（API 级别 23）及更高版本的手机、可折叠设备和平板电脑。如需将 Play Age Signals API 集成到您的应用中，请将以下依赖项添加到应用的 build.gradle 文件中：

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

请求年龄信号

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

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 VERIFIED, DECLARED, SUPERVISED, 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.
          }
        });

提示： 调用 Play Age Signals API 时，请使用 Play Integrity API 来验证调用是否来自经过认证的 Android 设备上未被篡改的应用版本，从而保护响应免遭潜在的欺骗或滥用。

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

在适用管辖区和地区，该 API 返回的默认年龄段为 0-12 岁、13-15 岁、16-17 岁和年满 18 周岁。

或者，您也可以根据应用的最低年龄要求自定义默认年龄段，只需在 Google Play 管理中心的年龄信号页面上提供应用的最低年龄要求即可。返回的年龄段将替换默认 API 响应。例如，如果您提供的最低年龄分别为 9 岁、15 岁和 17 岁，那么 14 岁的用户就会归入 10-15 岁年龄段。

如需自定义 Age Signals API 返回的默认年龄段，您可以为应用提供最低年龄要求：

1. 前往 Play 管理中心内的年龄信号页面。
2. 在自定义年龄段标签页上，为您的应用输入最多三个最低年龄。最低年龄之间必须至少相差 2 岁，且每年只能更改一次。
3. 点击 Save。

年龄信号响应

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

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

面向巴西用户的回答示例

在巴西，userStatus 只能是 DECLARED 和 UNKNOWN。

注意： 请使用 0.0.3 或更高版本的库来接收 DECLARED 作为用户状态。早期版本的库将返回 null 而不是 DECLARED。

对于声明了年龄的用户，您会收到以下信息：

• userStatus 将为 AgeSignalsVerificationStatus.DECLARED。
• ageLower 将是一个数字（例如 13）。
• ageUpper 应为数字或 null（例如 15）。
• 其他响应字段将为 null。

对于年龄未知的用户，您会收到以下信息：

• userStatus 将为 AgeSignalsVerificationStatus.UNKNOWN。
• 其他响应字段将为 null。

当用户可以分享自己的年龄时，用户状态可能会从 UNKNOWN 变为 DECLARED。

面向美国各州用户的回答示例

在美国的适用州，userStatus 可以是 VERIFIED、SUPERVISED、SUPERVISED_APPROVAL_PENDING、SUPERVISED_APPROVAL_DENIED、UNKNOWN 或 null。

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

• userStatus 将为 AgeSignalsVerificationStatus.VERIFIED。
• ageLower 将是一个数字（例如 18）。
• ageUpper 可以是数字或 null（例如 null）。
• 其他响应字段将为 null。

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

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

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

• userStatus 将为 AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING。
• ageLower 将是一个数字（例如 13）。
• ageUpper 应为数字或 null（例如 15）。
• mostRecentApprovalDate 将是 Java 日期对象（例如 2026-01-01）或 null（如果尚未批准任何重大更改）。
• 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 获取您的应用。	否
-10	SDK_VERSION_OUTDATED	Play 年龄信号 SDK 版本已不再受支持。 要求用户将您的应用更新到使用最新版 Play Age Signals SDK 的更高版本。	否
-100	INTERNAL_ERROR	未知内部错误。 实现重试策略，并将尝试次数上限作为退出条件。如果问题仍未解决，请让用户稍后再试。 如果该测试一直失败，请与 Google Play 开发者支持团队联系，并在主题中添加 Play Age Signals API，同时尽可能详细地提供技术信息（例如 bug 报告）。	否