使用 Play 年齡信號 API (Beta 版)

// 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.
        }
    }

// 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.
          }
        });

(選用) 接收自訂年齡層

在適用管轄區和區域，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. 按一下 [儲存]。

年齡信號回應

Play Age Signals API (Beta 版) 回應包含下列欄位和值。這些值可能會有所變動。如要取得最新值，請在應用程式開啟時要求 API 回應。您有責任使用這些信號，提供適合各年齡層的體驗。

巴西使用者的回應範例

在巴西，userStatus 只能是 DECLARED、UNKNOWN 或 null。

如果使用者已聲明年齡並與應用程式分享，您會收到下列資訊：

• userStatus 會是 AgeSignalsVerificationStatus.DECLARED。
• ageLower 會是數字 (例如 13)。
• ageUpper 應為數字或 null (例如 15)。
• 其他回應欄位為 null。

如果使用者年齡不詳，您會收到以下資訊：

• userStatus 會是 AgeSignalsVerificationStatus.UNKNOWN。
• 其他回應欄位為 null。

如果使用者未與應用程式分享年齡，您會收到下列資訊：

• userStatus 會是 null。
• 其他回應欄位為 null。

使用者可分享年齡後，狀態就會變更為 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 商店應用程式版本過舊。

重試策略

在使用者處於工作階段中時，建議您實作重試策略，並以最大重試次數做為結束條件，盡可能避免錯誤干擾使用者體驗。