使用 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 管理中心的「年齡信號」頁面，為應用程式提供這些最低使用年齡。

1. 前往 Play 管理中心的「年齡信號」頁面。
2. 在「自訂年齡範圍」分頁中，輸入應用程式最多三個最低年齡。各最低年齡間需相差至少 2 歲，且每年只能修改一次。
3. 按一下 [儲存]。

傳回的年齡層範圍會覆寫預設的 API 回應。例如：

• 如果您在 Google Play 管理中心設定一個最低年齡 (15 歲)：

  • 如果是 0 到 14 歲，則會傳回 ageLower = 0 和 ageUpper = 14。
  • 年滿 15 歲者會回傳 ageLower = 15。

• 如果設定兩個最低年齡 (13 歲和 17 歲)：

  • 0 到 12 歲的兒童會看到 ageLower = 0 和 ageUpper = 12。
  • 如果是 13 到 16 歲，則會傳回 ageLower = 13 和 ageUpper = 16。
  • 年滿 17 歲，則會傳回 ageLower = 17。

• 如果設定三個最低年齡 (11 歲、13 歲和 15 歲)：

  • 0 到 10 歲的兒童會傳回 ageLower = 0 和 ageUpper = 10。
  • 如果是 11 或 12 歲，則會傳回 ageLower = 11 和 ageUpper = 12。
  • 如果是 13 或 14 歲，則會傳回 ageLower = 13 和 ageUpper = 14。
  • 年滿 15 歲者會回傳 ageLower = 15。

年齡信號回應

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)。
• 會是 Java 日期物件 (例如 2026-01-01) 或 null (如果沒有核准重大變更)。mostRecentApprovalDate
• installID 是 Play 產生的英數字元 ID (例如 550e8400-e29b-41d4-a716-446655441111)。

如果受監護使用者有待核准的重大變更，您會收到下列訊息：

• userStatus 會是 AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING。
• ageLower 會是數字 (例如 13)。
• ageUpper 會是數字或 null (例如 15)。
• 會是 Java 日期物件 (例如 2026-01-01) 或 null (如果沒有核准重大變更)。mostRecentApprovalDate
• installID 是 Play 產生的英數字元 ID (例如 550e8400-e29b-41d4-a716-446655441111)。

處理 API 錯誤代碼

如果應用程式發出 Play Age Signals API 要求，但呼叫失敗，應用程式會收到錯誤代碼。造成這些錯誤的原因有很多，例如 Play 商店應用程式版本過舊。

重試策略

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