如果您已透過信任的伺服器驗證回應，那麼從 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
|
deviceRecognitionVerdict
|
FALSE |
FALSE |
沒有標籤 | |
FALSE |
TRUE |
MEETS_BASIC_INTEGRITY |
|
TRUE |
FALSE |
沒有標籤 | |
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 回應。
在完全停用前持續接收回應
如果您在遷移期限 (2024 年 1 月 31 日) 前尚未遷移至 Play Integrity API 或移除 SafetyNet Attestation，可以填寫這份表單申請延期。如果獲准延期，應用程式會持續收到 SafetyNet Attestation 的回應，直到完全停用期限 (2025 年 1 月 31 日) 為止。