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

使用 Play 年齡信號 API (測試版) 即表示您同意服務條款，並遵守所有 Google Play 開發人員政策。如要要求取得使用者的狀態和年齡層，請在執行階段從應用程式呼叫 API。當使用者位於 Google Play 依法必須提供年齡類別資料的地區時，Play Age Signals API 才會傳回他們的資料。

Play 會根據適用管轄區和地區定義的年齡層，傳回年齡範圍。在適用管轄區和區域，API 傳回的預設年齡層為 0-12 歲、13-15 歲、16-17 歲和 18 歲以上，但這些年齡層可能會根據區域規定而異。

將 Play Age Signals API 整合到應用程式中

Android 6.0 (API 級別 23) 以上版本支援 Play 年齡信號 API。如要將 Play 年齡信號 API 整合到應用程式中，請在應用程式的 build.gradle 檔案中新增下列依附元件：

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

要求年齡信號

以下是發出年齡信號要求的範例：

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

Google Play 會在裝置上儲存每位使用者的年齡信號。如果受監護的 Google 帳戶使用者進入新的年齡範圍，Google Play 會在使用者生日後的 2 到 8 週內，自動更新該使用者的快取年齡信號。

(選用) 接收自訂年齡層

在適用管轄區和區域，API 傳回的預設年齡層為 0-12 歲、13-15 歲、16-17 歲和 18 歲以上。這些年齡層日後可能會根據當地規定調整。

如要根據應用程式的最低使用年齡自訂年齡層，請前往 Google Play 管理中心的「年齡信號」頁面，提供應用程式的最低使用年齡。Age Signals API 會傳回自訂年齡層。 舉例來說，若設定的最低年齡為 9 歲、15 歲和 17 歲，14 歲使用者會歸類在 10 至 15 歲的年齡層。

如要自訂 Age Signals API 傳回的年齡層，請提供應用程式的最低年齡：

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

年齡信號回應

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

回應欄位 值 說明
userStatus 已驗證 使用者年滿 18 歲。Google 會使用商業上合理的驗證方法 (例如政府核發的身分證件、信用卡或臉部年齡估算) 驗證使用者年齡。如果 userStatus 為 VERIFIED，您可以忽略其他欄位。
受監護 使用者擁有受監護的 Google 帳戶，且帳戶年齡由家長設定。 使用 ageLower 和 ageUpper 判斷使用者的年齡範圍。 使用 mostRecentApprovalDate 判斷上次核准的重大變更。
SUPERVISED_APPROVAL_PENDING 使用者擁有受監護的 Google 帳戶，且監護家長尚未核准一或多項待處理的重大變更。 使用 ageLower 和 ageUpper 判斷使用者的年齡範圍。 使用 mostRecentApprovalDate 判斷上次核准的重大變更。
SUPERVISED_APPROVAL_DENIED 使用者擁有受監護的 Google 帳戶，且監護家長拒絕核准一或多項重大變更。 使用 ageLower 和 ageUpper 判斷使用者的年齡範圍。 使用 mostRecentApprovalDate 判斷上次核准的重大變更。
不明 使用者位於適用管轄區或區域，但未通過驗證或受到監督。這些使用者可能年滿 18 歲，也可能未滿 18 歲。如要從 Google Play 取得年齡信號，請要求使用者前往 Play 商店解決狀態問題。
null 其他使用者則會傳回這個值。如果 userStatus 為 null，您可以忽略其他欄位。
ageLower 0 至 18 受監督使用者年齡範圍的下限 (含)。 使用 ageLower 和 ageUpper 判斷使用者的年齡範圍。
null
 userStatus不明或空白。
ageUpper 2 至 18 歲 受監督使用者年齡範圍的上限 (含)。 使用 ageLower 和 ageUpper 判斷使用者的年齡範圍。
null userStatus受到監護，且使用者家長聲明年滿 18 歲。 或 userStatus 為已驗證、不明或空白。
mostRecentApprovalDate 日期戳記 最近一次獲准重大變更的effective from日期。安裝應用程式時，系統會使用安裝前最近一次重大變更的日期。
null userStatus 受到監督，且未提交重大變更。 或 userStatus 為已驗證、不明或空白。
installID Play 產生的英數字元 ID。 Google Play 指派給受監護使用者安裝的 ID，用於通知您應用程式核准遭撤銷。 請參閱撤銷應用程式核准的說明文件。
null userStatus 為已驗證、不明或空白。

回覆範例

通過驗證的使用者會收到以下資訊：

  • userStatus 會是 AgeSignalsVerificationStatus.VERIFIED。
  • 其他回應欄位則會留空。

如果是受監護的使用者，您會收到以下訊息：

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

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

  • userStatus 會是 AgeSignalsVerificationStatus.SUPERVISED_APPROVAL_PENDING。
  • ageLower 會是數字 (例如 13)。
  • ageUpper 會是數字 (例如 15)。
  • mostRecentApprovalDate 會是 Java 日期物件 (例如 2026-01-01)，或是空白 (如果沒有核准重大變更)。
  • 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 取得您的應用程式。 否
-100 INTERNAL_ERROR 未知的內部錯誤。 實作重試策略，並以最大重試次數做為結束條件。如果問題仍未解決，請要求使用者稍後再試。 如果持續失敗，請與 Google Play 開發人員支援團隊聯絡，並在主旨中加入 Play Age Signals API，盡可能提供詳細的技術資訊 (例如錯誤報告)。 否
上一頁
總覽
下一頁
通知重大變更