如果您已在使用受信任伺服器驗證回應，那麼從 SafetyNet Attestation API 遷移至 Play Integrity API 是非常簡單的程序。Play Integrity API 也可以用來取代透過 AIDL 直接使用 Play 商店應用程式執行的應用程式授權檢查，例如由授權驗證庫 (LVL) 執行的檢查。大多數的必要變更都發生受信任伺服器端，而伺服器需要讀取及分析 Play Integrity 回應權杖。請注意，在遷移期間，應用程式和伺服器都需要同時支援這兩種 API，以便支援尚未更新的舊用戶端。
如果應用程式已經獲得更高的 SafetyNet Attestation API 配額限制，您應前往檢查 Play Integrity API 所指派的用量層級，而如果有必要的話，請要求遷移到提高過後的層級。
如要支援 Play Integrity API，必須進行以下變更：
Android 用戶端：
- 確保程式碼會將正確格式的 Nonce 傳遞至
IntegrityTokenRequest建構工具：String(而非位元組陣列)- 具有網址安全性
- 編碼為 Base64 且沒有換行
- 至少 16 個字元
- 最多 500 個字元
- 查看重試邏輯，並確保應用程式能夠正確處理錯誤。
- 確保傳送至受信任伺服器的回應資料可以區分 SafetyNet Attestation API 回應與 Play Integrity API 回應。
受信任伺服器：
- 檢查 Nonce 產生邏輯，並確認其符合 Play Integrity API 要求。
- 確保伺服器程式碼可以區分 SafetyNet Attestation API 回應和 Play Integrity API 回應。確保此程式碼能夠正確剖析和驗證這些回應。
- 新增邏輯以驗證和剖析 Play Integrity API 回應。
- 由於新的 Play Integrity API 回應提供了額外的詳細資料，因此可能需要增強決策邏輯與傳回用戶端裝置的意見回饋資料。詳情請參閱本主題中的「API 回應對應」一節。
Nonce 編碼
與完整性相關的 Nonce 必須以 String 形式傳送給 Play Integrity API，並需要以 Base64 編碼、具有網址安全性且沒有換行。這種格式與需要 byte[] 的 SafetyNet Attestation API 不同。
- 「具有網址安全性」是指使用 Base64 的「網址和安全檔案名稱」變體 (請參閱 RFC 4648 第 5 節)，其中將「-」和「_」用於取代「+」和「/」。如要進一步瞭解 Base64 編碼，請參閱「RFC 4648」。
- 「沒有換行」表示省略所有行終止符。這代表輸出內容為一長串。
.setNonce(Base64.encodeToString(NONCE_BYTES,
Base64.URL_SAFE | Base64.NO_WRAP))
此外，請確認 Nonce 值符合「Play Integrity API 規範」。
API 回應對應
下表列出了 SafetyNet Attestation API 欄位與其 Play Integrity API 同等欄位之間的對應關係。
| SafetyNet Attestation API | Play Integrity API | 附註 | |
timestampMs |
requestDetails.timestampMillis
|
||
nonce |
requestDetails.nonce |
||
apkPackageName |
appIntegrity.packageName
|
||
apkCertificateDigestSha256
|
appIntegrity.certificateSha256Digest
|
確認 appRecognitionVerdict 已設為 PLAY_RECOGNIZED
|
|
ctsProfileMatch |
合併至 deviceIntegrity.deviceRecognitionVerdict
|
||
basicIntegrity |
合併至 deviceIntegrity.deviceRecognitionVerdict
|
||
evaluationType |
合併至 deviceIntegrity.deviceRecognitionVerdict
|
||
advice |
Not available |
||
error
|
Not available
|
裝置完整性標籤清單將為空白。 |
裝置完整性判定結果對應
| SafetyNet Attestation API | Play Integrity API | ||
ctsProfileMatch
|
basicIntegrity
|
evaluationType
|
device_recognition_verdict
|
FALSE |
FALSE |
Empty labels
|
|
FALSE |
TRUE |
MEETS_BASIC_INTEGRITY |
|
TRUE |
FALSE |
Empty labels |
|
TRUE |
TRUE |
BASIC
|
MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
|
TRUE |
TRUE |
HARDWARE_BACKED |
MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY,
MEETS_BASIC_INTEGRITY
|
如果您的應用程式採用複雜的強制執行策略，並需要所有可能的值，您可能需要設定裝置完整性回應組合。
Play Integrity API 重試邏輯
發生特定錯誤代碼時，應用程式應該重試 API 呼叫。請務必查看所有錯誤代碼，並確保應用程式會在必要時透過指數輪詢重試。請確保最短延遲時間至少為 5 秒，並以指數方式遞增 (5 秒、10 秒、20 秒、40 秒等)，以便為 API 提供足夠的時間來評估裝置和應用程式完整性。
可選 App Licensing API 替代方法
如果您使用的是 App Licensing API，可以選擇遷移以使用 Play Integrity API，因為 Play Integrity API 權杖包含應用程式的授權資訊。與 SafetyNet Attestation API 遷移一樣，可能會有許多裝置保留了舊版應用程式。受信任伺服器應能處理 App Licensing API 和 Play Integrity API 回應。