要求年齡信號

本文說明如何使用 Play 年齡信號 API 要求年齡信號。

Play 年齡信號 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 和其他重大變更值。
上一頁
使用年齡信號
下一頁
瞭解年齡信號回應