設備證明 Level 2：Google Play Integrity API（平台替你判定）

L0 的骨架是：平台在保險箱裡蓋章，伺服器端負責驗章。L0 也預告過：Google 有一種請求方式由平台自動防重送，你只要把這次請求的內容綁進去。這一站就把那句話對上具體名詞，看 Android 上的 Play Integrity API 怎麼跑。

這站學完，你要能用自己的話回答：
① standard 請求和 classic 請求各在什麼時候用？各自怎麼防重送？
② 判定結果分成哪幾類？每一類在問什麼？
③ 伺服器拿到判定結果後，除了「放行／拒絕」還能怎麼回應？
④ 跟 Apple App Attest 比，Google 最大的不同在哪？

先認得這站的新名詞

角色對應：L0 的「平台」在這裡＝Google Play 元件（在手機上）＋安全硬體＋Google 伺服器。

比喻延續「章」：Apple 是「開印鑑證明給你，伺服器自己存樣本、自己驗章」；Google 則像把蓋好章的密封信封交給你（信封＝加密，章＝簽章），你拿去 Google 的驗件窗口拆封，窗口直接告訴你結論。

Play Integrity 是什麼

• 它回答三個核心問題：App 有沒有被改過、裝置是不是真的認證裝置、使用者是不是從 Google Play 取得 App。
• 跟 L0 講的「硬體保護的金鑰」的關係：Play Integrity 評估裝置時，會用到硬體保護的安全訊號。官方把這句連到 Android 的 Key Attestation（Android 用硬體金鑰替裝置作證的底層機制）。但它把不同 Android 版本、不同廠商金鑰的複雜度都包起來，你拿到的是結論，不用自己處理憑證鏈。要注意：Android 13 以前的 MEETS_DEVICE_INTEGRITY 在沒有硬體時，會退回軟體證明。
• 它不是唯一防線：官方說它最適合搭配其他訊號，當作整體防濫用策略的一部分。

兩種請求方式，判定結果的格式一樣：

註：最低 Android 版本以 Overview 頁和 classic 頁的比較表為準，現行 library 兩種都是 Android 6.0 以上；standard、classic 頁首寫的 5.0／4.4 是 v1.3.0 以前的數字。

一句話：Play Integrity 是 Google 版的設備證明；大多數情況用 standard 請求，classic 只留給少數關鍵操作。

standard 請求：流程

分兩段：事先準備，之後每次需要時要一個 token。

圖 A：standard 請求。Google Play 元件背後用到安全硬體的訊號，但那屬於平台，不在你的 App 裡（點圖可放大）

事先準備（prepare／warm up）

• App 用 StandardIntegrityManager（App 端發 standard 請求的入口物件）呼叫 prepareIntegrityToken()，帶上你的 Google Cloud 專案編號（你在 Google Cloud 開的專案的編號，用來計算用量），拿到一個 token provider（準備好之後拿來要 token 的物件），放在記憶體裡。
• 為什麼要先準備：讓 Google Play 先在裝置上準備好部分證明資訊，之後真正要 token 時就快很多。
• 什麼時候做：App 啟動時、或在背景提前做。準備會連到伺服器，通常幾秒、大多數 10 秒內，官方建議逾時設長一點（例如 1 分鐘）。
• 準備不是註冊：它不產生要你的伺服器保存的金鑰；token provider 用久了會過期；可以重做，每個 App 實例（一支手機上執行中的那份 App）每分鐘最多 5 次。

每次需要時：綁 requestHash、拿 token

1. 算 requestHash：把這次操作的所有相關參數，用固定的方式排好再做雜湊（例如 SHA256）。最長 500 bytes。
2. 要 token：用 StandardIntegrityTokenRequest 的 setRequestHash 帶入，呼叫 token provider 的 request()。
3. 送到你的伺服器：把 token 和原本的請求一起送出。
4. 交給 Google 解密：你的伺服器用 service account 取得存取權，呼叫 decodeIntegrityToken，拿回判定結果。

// Request integrity token by providing a user action request hash.
String requestHash = "2cp24z...";
Task<StandardIntegrityToken> integrityTokenResponse =
    integrityTokenProvider.request(
        StandardIntegrityTokenRequest.builder()
            .setRequestHash(requestHash)
            .build());

（程式碼摘自 Android Developers 官方文件。）

requestHash 要綁什麼、怎麼驗

• 綁什麼：跟這個操作有關的所有重要值。官方的例子是遊戲回報分數：把分數綁進去，伺服器就能確定分數沒被中途改掉。
• 為什麼要綁：沒有 requestHash，token 只跟裝置綁在一起、不跟這則請求綁在一起，就留下攻擊空間。
• 伺服器怎麼驗：用跟 App 一樣的方式重算一次雜湊，跟判定結果裡的 requestHash 比對。不一樣就不能信。
• 別放明文：這個值 App 和 Google 都看得到明文，敏感資料一律先雜湊。

Google 怎麼替你防重送

standard 請求自動防重送：Google Play 會阻止同一個 token 被重複使用很多次。同一個 token 被重複解密時，判定結果會被清空：

• 裝置的判定變成空的。
• App 與帳號的判定變成 UNEVALUATED（未評估）。
• 在 Play Console 開啟的選用判定也變成 UNEVALUATED（多值的判定則變成空的）。

Google 擋的是大量重複使用，timestampMillis 還是要你自己檢查。對回 L0 的三項檢查，standard 下是這樣分工：

• 對不對＝你比對 requestHash。
• 用過沒＝Google 替你做。
• 過期沒＝你檢查 timestampMillis。

一句話：standard 請求＝事先準備 → 每次把請求內容綁進 requestHash 拿 token → 你的伺服器交給 Google 解密；「用過沒」由 Google 處理，「對不對」和「過期沒」你自己查。

classic 請求：只留給少數關鍵操作

• 什麼時候用：偶爾一次、檢查最有價值或最敏感的操作，想在 standard 之外多一層保證時。它比較耗時間、流量和電，也有每日次數上限；不要每次 App 回到前景就叫。
• 想快取它就改用 standard：官方說，如果你打算做一次 classic 請求再快取起來用，應該改做 standard 請求。
• 流程：用 IntegrityManager 的 requestIntegrityToken()，帶一個 nonce。之後一樣把 token 送到你的伺服器。

nonce 由誰產生、怎麼防重送

• 最好由伺服器產生：一個惡意使用者猜不到的全域唯一值，例如伺服器端的密碼學安全亂數，或既有的 session／交易 ID；官方建議 128 bits 以上。在裝置上產生也可以，但比較不安全。
• 防重送：伺服器要記錄發過（或看過）的值。收到判定結果時，值沒發過或已經用過，就拒絕。
• 同時防竄改：把唯一值放進要保護的訊息裡，再對整個訊息做雜湊，拿雜湊當 nonce。伺服器重算雜湊比對，同時檢查唯一值。
• 格式：URL-safe、不換行的 Base64 字串，16～500 個字元。

名詞提醒：三個長得像的東西
・L0 的 challenge：伺服器發的一次性亂數，泛稱。
・classic 的 nonce：你交給 Play Integrity 的欄位值，內容是唯一值，或「唯一值＋訊息」的雜湊；會原封不動出現在判定結果裡。
・L1 Apple 的 nonce：你的伺服器用 authData 和 clientDataHash 算出來比對用的值，不是你送出去的。

token 解密的兩種方式

1. 交給 Google 伺服器解密（官方建議）：跟 standard 一樣，呼叫 decodeIntegrityToken。
2. 自己解：classic 可以選擇自己保管 Play Console 給的金鑰，在自己的伺服器解密、驗章；standard 只能交給 Google 解。

一句話：classic＝你自己產生唯一的 nonce、自己記錄防重送；token 可交給 Google 解，也可自己解。

判定結果：五類，各自在問什麼

不管 standard 或 classic，判定結果都是同一種格式的 JSON。官方要求先驗 requestDetails，再看其他類別。

圖 B：判定結果的五個類別（點圖可放大）

1. requestDetails：這是我這次的請求嗎？套件名稱要是你的 App，requestHash（classic 是 nonce）要對上，timestampMillis 要夠新。
2. appIntegrity：是那個沒被改過的 App 嗎？看 App 和它的簽章憑證是否符合 Google Play 發行的版本。
3. deviceIntegrity：裝置可信嗎？回傳一個或多個等級標籤；一個都不符合，就沒有標籤。
4. accountDetails：使用者是從 Google Play 取得的嗎？看這個帳號有沒有這個 App 的 Play 授權。
5. environmentDetails（選用）：執行環境有沒有風險？要在 Play Console 開啟才會出現。

一句話：先確認 requestDetails（是這次的請求），再看 App、裝置、帳號、環境各自可不可信。

拿到判定結果後怎麼決定

先過基本檢查，再分級

1. 基本檢查：requestDetails 對上；appRecognitionVerdict 是 PLAY_RECOGNIZED；appLicensingVerdict 是 LICENSED。
2. 依裝置可信度分級。先知道兩件事：一台裝置會拿到它符合的所有標籤，而除了預設標籤，其他標籤要先在 Play Console 開啟；同一個標籤在 Android 13 前後標準不同。從高到低：
   • MEETS_STRONG_INTEGRITY（Android 13 以上）：最高級，要硬體訊號加上近期安全更新。
   • MEETS_DEVICE_INTEGRITY（Android 13 以上）與 MEETS_STRONG_INTEGRITY（Android 13 以前）：都靠硬體訊號。
   • MEETS_DEVICE_INTEGRITY（Android 13 以前）：有硬體就用硬體證明，沒有就退回軟體證明。
   • MEETS_BASIC_INTEGRITY：最弱的一級，再下去就是沒有任何標籤。
3. 再疊其他訊號：例如 recentDeviceActivity 等級高的裝置，信任度就調低。

Android 13 前後差在哪：Android 13 以上，MEETS_DEVICE_INTEGRITY 要有硬體證明開機程式鎖定、系統是原廠認證映像；MEETS_STRONG_INTEGRITY 還要裝置所有分割區在一年內有安全更新。Android 12 以下的 MEETS_STRONG_INTEGRITY 只要求硬體證明開機完整性、不要求近期更新，所以要搭配 deviceAttributes 的 sdkVersion 一起判斷。

官方提醒：越高等級的裝置越少，只認最高等級會擋掉很多人，所以建議分級處理。

回應不只放行和拒絕

• 官方原句：可以用一系列相關的回應，例如 Allow、Allow with limits、Allow with limits after CAPTCHA completion（完成「我不是機器人」驗證後限制放行）、Deny。
• 官方也建議正式擋人前，先只收集判定結果、不執行，看清現有使用者的分布再決定。

（兩個平台共用的處理策略見 L3。）

補救流程：判定有問題時，App 可以用 showDialog 跳出 Google Play 的對話框請使用者自己修，例如 GET_LICENSED 引導到 Google Play 取得正版；要跳哪一種，由伺服器看完判定結果後決定。關掉對話框後再要一次 token 確認（standard 要重新準備）。

一句話：先過三項基本檢查，再依裝置等級分級回應；有問題時可以請使用者自己補救。

跟 L1 的 Apple App Attest 對照

兩邊差這麼多，伺服器要怎麼用同一套邏輯處理，是 L3 的主題。

常見的坑

• 每日配額：預設「取 token」（classic 請求與 standard 的準備共用）和「在 Google 伺服器解密」每天各 10,000 次。要提高，得先把 Cloud 專案連結到 Play Console，再照 Setup 頁送出申請。
• 每分鐘上限（每個 App 實例）：standard 準備 5 次、取 token 沒有公開上限；classic 取 token 5 次。所有請求在量很大時，仍受非公開的防禦性上限約束。
• 不要快取判定結果：快取會提高 proxying（代理攻擊）的風險：壞人拿好裝置的判定結果，去別的環境冒用。需要時就做一次 standard 請求。
• 時效：官方沒有公布 token 的固定有效期限；伺服器要自己訂一個允許的時間窗（官方範例叫 ALLOWED_WINDOW_MILLIS），timestampMillis 太舊就不收。token provider 用太久也會過期，下次請求出現 INTEGRITY_TOKEN_PROVIDER_INVALID，這時要重新準備一個。
• Android 13 前後標準不同：記得配 sdkVersion 判斷（見上方分級）。
• 沒有 Google Play 元件的裝置：兩種請求都需要 Google Play Store 和 Google Play services。其中的 Google Play services 不可用或太舊時，會出現 PLAY_SERVICES_NOT_FOUND，可以用 GET_INTEGRITY 或 GET_STRONG_INTEGRITY 對話框引導使用者安裝或更新。
• 錯誤重試：暫時性錯誤才重試。背景操作：用指數退避（每次重試的等待時間加倍：5 秒起、10 秒、20 秒）；重試三次仍失敗，就當作沒通過所有檢查。

一句話：配額要申請、結果別快取、時間戳要檢查、Android 13 前後標準不同、沒有 Google Play 元件就拿不到。

✔ 過關標準

能不看筆記回答下面 5 題，這站就過了。

1. standard 和 classic 請求各在什麼時候用？看答案收合

   standard：大多數情況，隨時檢查任何操作，事先準備、之後很快。classic：偶爾一次，只給最有價值或最敏感的操作，比較慢也比較耗資源。
2. 兩種請求各自怎麼防重送？看答案收合

   standard：Google Play 擋同一個 token 被大量重複使用（重複解密會清空結果）；你負責比對 requestHash、檢查 timestampMillis。classic：你自己產生唯一的 nonce，伺服器記錄用過的值，重複或沒發過的就拒絕。
3. 判定結果有哪五類？為什麼要先看 requestDetails？看答案收合

   requestDetails、appIntegrity、deviceIntegrity、accountDetails、environmentDetails（選用）。先看 requestDetails，是要確認這份結果真的是為你這次的請求產生的，其他類別才有意義。
4. 伺服器除了放行和拒絕，還能怎麼回應？看答案收合

   依裝置等級分級：例如 Allow、Allow with limits、Allow with limits after CAPTCHA completion、Deny；也可以由伺服器決定，請 App 跳出 Google Play 的補救對話框讓使用者自己修。
5. 跟 Apple App Attest 比，最大的不同是什麼？看答案收合

   Apple 要伺服器端的一次性註冊、你的伺服器自己驗證明、自己防重送；Google（standard）不用伺服器端註冊、由 Google 伺服器解密並擋重複使用，你拿到的是已經判斷好的結果。

下一站

Level 3 會回到伺服器端，看怎麼用同一套邏輯同時接住 Apple 和 Google 兩邊，以及驗證失敗時怎麼降級。

參考來源

• Android Developers — Overview of the Play Integrity API（三大判定、硬體訊號、搭配其他訊號、兩種請求比較表、分級與一系列回應、先收集再執行、不要快取）
• Android Developers — Make a standard API request（準備 token provider、requestHash、decodeIntegrityToken、自動防重送與清空規則、provider 過期）
• Android Developers — Make a classic API request（使用時機、nonce 的產生與格式、兩種解密方式、比較表與每分鐘上限）
• Android Developers — Integrity verdicts（判定結果的五個類別、各欄位與標籤、Android 13 前後的標準）
• Android Developers — Remediation dialogs（showDialog 與對話框類型）
• Android Developers — Set up Play Integrity API（Cloud 專案、連結 Play Console、每日配額與申請提高）
• Android Developers — Play Integrity API error codes（重試策略、PLAY_SERVICES_NOT_FOUND）
• Android Developers — Key and ID attestation（Overview 頁「硬體訊號」連到的底層機制）