请求年龄信号

本文档介绍了如何使用 Play 年龄信号 API 请求年龄信号。

Play Age Signals 0.0.4 SDK 引入了一种双函数架构，旨在简化年龄信号请求并支持基于用户选择的模型。如需请求年龄信号，请按以下大致流程操作：

调用 requestAgeSignalsAccess(Activity) 方法，该方法会返回 ageSignalsStatus。ageSignalsStatus 的值可以是 SHARED、NOT_SHARED 或 VERIFICATION_REQUIRED。

  • 如果值为 ageSignalsStatus == NOT_SHARED：您的应用不会在 API 响应中收到年龄信号。
  • 如果 ageSignalsStatus == SHARED：调用 checkAgeSignals() 方法。如果用户或家长决定分享年龄信号，您会在 API 响应中收到年龄信号，并可以决定如何处理该响应。
  • 如果值为 ageSignalsStatus == VERIFICATION_REQUIRED：用户年龄未知，且用户位于必须进行年龄验证和共享年龄信号的适用司法管辖区或区域。如需在这些地区从 Google Play 获取年龄信号，请让用户访问 Play 商店以解决其状态问题。

requestAgeSignalsAccess(Activity) 方法会根据强制性年龄分享是否适用于某个地区而返回不同的值：

  • 对于美国境内某些州的符合条件的用户，如果这些州有法律要求应用商店向开发者提供经过验证的年龄信息，则不会触发应用内提示。 用户访问 Play 商店应用时，系统会要求其进行验证或设置监督功能。您可以使用 ageSignalsStatus 的值来确定验证状态：
  • 对于其他地区的用户，年龄分享功能是否启用取决于用户或家长的选择：
    • 如果用户的设置为分享前询问，系统会显示应用内提示。如果用户同意分享其年龄，则 ageSignalsStatus 的值为 SHARED；否则为 NOT_SHARED。
    • 如果用户的设置是始终分享，则不会显示应用内提示，并且 ageSignalsStatus 的值为 SHARED。
    • 如果用户的设置是从不分享，则不会显示应用内提示，并且 ageSignalsStatus 的值为 NOT_SHARED。
    • 对于受监督的用户，家长可以在 Family Link 应用设置中选择是否分享孩子的年龄。如果父母双方选择共享年龄，则 ageSignalsStatus 的值为 SHARED，否则为 NOT_SHARED。

下图显示了 Play 设置中的分享前询问年龄段配置。

Google Play 设置菜单，其中显示了年龄分享选项：“分享前询问”“始终分享”和“从不分享”
图 1. 您可以在 Play 设置中管理年龄分享功能。

下图显示了通过 API 请求年龄时，如果用户的设置是分享前询问，系统向用户显示的年龄段分享应用内请求。

应用内意见征求对话框，提示用户与应用分享其年龄段。
图 2. 应用内年龄段信息分享请求。

下图显示了用户如何针对特定应用启用或停用年龄分享功能。

特定应用的“设置”对话框，其中显示了用于启用或停用年龄段分享功能的切换开关
图 3. 为特定应用启用或停用年龄共享功能。

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

Kotlin

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
val ageSignalsManager = AgeSignalsManagerFactory.create(applicationContext)

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
val accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build()

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener { accessResult ->
        if (accessResult.ageSignalsStatus() == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager)
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    }
    .addOnFailureListener { exception ->
        // Handle API/Play Store connection and system errors
        handleAgeSignalsError(exception)
    }

private fun retrieveAgeSignals(manager: AgeSignalsManager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener { ageSignalsResult ->
            val installId = ageSignalsResult.installId()
            val ageLower = ageSignalsResult.ageLower()
            val ageUpper = ageSignalsResult.ageUpper()
            val significantChangeDate = ageSignalsResult.significantChangeApprovalDate()
            val ageRangeSource = ageSignalsResult.ageRangeSource()

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        }
        .addOnFailureListener { exception ->
            handleAgeSignalsError(exception)
        }
}

Java

// 1. Initialize the AgeSignalsManager (usually in onCreate or class initialization)
AgeSignalsManager ageSignalsManager = AgeSignalsManagerFactory.create(getApplicationContext());

// 2. Request or check for age signals access.
// Passing the current Activity allows the Play Store to render the age sharing prompt UI if required.
AgeSignalsAccessRequest accessRequest = AgeSignalsAccessRequest.builder()
    .setActivity(this)
    .build();

ageSignalsManager.requestAgeSignalsAccess(accessRequest)
    .addOnSuccessListener(accessResult -> {
        Integer status = accessResult.ageSignalsStatus();
        if (status == AgeSignalsStatus.SHARED) {
            // The user (or parent) has agreed to share age range, or is in an eligible auto-share region.
            // Retrieve the actual age signals.
            retrieveAgeSignals(ageSignalsManager);
        } else {
            // Age signals are not shared (user didn't share age range, parent rejected the request, or not eligible).
        }
    })
    .addOnFailureListener(exception -> {
        // Handle API/Play Store connection and system errors
    });

private void retrieveAgeSignals(AgeSignalsManager manager) {
    // 3. Perform the actual age signals query once sharing is active.
    manager.checkAgeSignals(AgeSignalsRequest.builder().build())
        .addOnSuccessListener(ageSignalsResult -> {
            String installId = ageSignalsResult.installId();
            Integer ageLower = ageSignalsResult.ageLower();
            Integer ageUpper = ageSignalsResult.ageUpper();
            Date significantChangeDate = ageSignalsResult.significantChangeApprovalDate();
            @AgeRangeSource Integer ageRangeSource = ageSignalsResult.ageRangeSource();

            if (ageLower != null) {
                if (ageUpper != null) {
                    // The user is in a specific closed age range [ageLower, ageUpper] (e.g. [13, 15])
                } else {
                    // The user is in the highest open-ended age band [ageLower, null] (e.g. [18, null])
                }
            } else {
                // Both bounds are null: The user is not sharing their age (e.g. they are a verified adult)
            }
        })
        .addOnFailureListener(exception -> {
            handleAgeSignalsError(exception);
        });
}

代码要点

  • requestAgeSignalsAccess(Activity) 方法会以阻塞方式检查用户的当前年龄信号和年龄信号分享状态。
  • 调用 requestAgeSignalsAccess(Activity) 后，Play 仅会向非监督用户显示内置的应用内提示。受监督用户的家长可以选择分享孩子的年龄，方法是在 Family Link 应用中管理年龄共享设置。
  • 如果用户关闭或拒绝分享年龄，系统会显示几次应用内提示，然后才会停止显示提示。
  • checkAgeSignals() 方法用于获取 API 响应中的年龄信号值。此方法会返回 ageRangeSource、ageUpper、ageLower 和其他重大更改值。
上一页
使用年龄信号
下一页
了解年龄信号响应