本頁面說明如何設定應用程式或遊戲來使用 Play Integrity API。您需要啟用來自這個 API 的回應，然後將這個 API 整合至應用程式和應用程式的後端伺服器。當您在 Google Play 管理中心連結 Play Integrity API 所用的 Google Cloud 專案後，即可使用其他設定選項、測試功能和報告。
啟用 Play Integrity API 回應
凡是會呼叫 Play Integrity API 的應用程式或 SDK，都必須使用 Google Cloud 專案監控 API 用量。Google Play 上的應用程式可以在 Google Play 管理中心連結 Cloud 專案，啟用 Play Integrity API 回應功能。如果您想建立新的 Cloud 專案，或只在 Google Play 以外的管道發行應用程式，可以透過 Google Cloud 控制台啟用 Play Integrity API 回應。
在 Google Play 管理中心設定 (建議做法)
只要在 Google Play 管理中心啟用 Play Integrity API 回應，即可存取其他設定選項、測試功能和 API 報告。這個做法僅適用於在 Google Play 發行的應用程式。請依序前往「發布」>「應用程式完整性」。接著在「Play Integrity API」下方，選取「連結 Cloud 專案」。然後選擇要連結至應用程式的 Cloud 專案，這會啟用 Play Integrity API 回應。完成後，即可將 Play Integrity API 整合到應用程式中。
在 Google Cloud 控制台設定
請在 Google Cloud 控制台中建立新的 Cloud 專案，或選擇要搭配 Play Integrity API 使用的現有 Cloud 專案。接著前往「API 和服務」，選取「啟用 API 和服務」，搜尋「Play Integrity API」，然後啟用該 API。完成後，即可將 Play Integrity API 整合到應用程式中。
SDK 供應商專用的設定說明
SDK 供應商必須使用自己的 Google Cloud 專案呼叫 Play Integrity API，這樣 API 用量才會歸給 SDK，而非採用該 SDK 的個別應用程式。也就是說，使用 SDK 的應用程式不必個別設定 Play Integrity API。您向 Play Integrity API 提出的要求會自動計入 SDK 的 API 用量，而非應用程式的用量。
SDK 開發人員有兩種方式可以設定 Play Integrity API，也就是 Google Play SDK 管理中心或 Google Cloud 控制台。
使用 Google Play SDK 管理中心 (建議做法)
只要在 Google Play SDK 管理中心啟用 Play Integrity API 回應，即可存取其他設定選項。前往「SDK 完整性」，然後按一下「設定」。接著在「專案設定」下方，選取「連結 Cloud 專案」，然後選擇要連結至 SDK 的 Cloud 專案，這會啟用 Play Integrity API 回應。完成後，即可將 Play Integrity API 整合到 SDK 中。請注意，您必須符合資格條件，才能存取 Google Play SDK 管理中心。
使用 Google Cloud 控制台
您可以透過 Google Cloud 控制台啟用 Play Integrity API 回應。請在 Google Cloud 控制台中建立新的 Cloud 專案，或選擇要搭配 Play Integrity API 使用的現有 Cloud 專案。接著前往「API 和服務」，選取「啟用 API 和服務」，搜尋「Play Integrity API」，然後啟用該 API。完成後，即可將 Play Integrity API 整合到 SDK 中。
提高 SDK 的每日 Play Integrity API 要求數
如果 SDK 供應商想要提高每日要求數量上限，應填寫配額申請表單。請在公開的備註欄中，指明您要提出 SDK 要求，並加入 Maven 座標 (groupId:artifactId) 或 SDK 的網址。
提高每日 Play Integrity API 要求數
每個應用程式每天最多總共只能提出 10,000 個要求。如果應用程式需要處理更多使用者，可以按照以下說明，要求提高每日上限。
調高每日要求數量上限
除了在任何其他發行管道外，您的應用程式也必須在 Google Play 上架，這樣您才有資格申請調高每日的要求數量上限。即使每日上限已上調，您仍應繼續將每位使用者的傳統要求限制為不常執行的重要操作，以便保留使用者資料和電池電力。
如要申請調高每日要求數量上限，請完成下列操作：
- 在 Play 管理中心連結 Play Integrity API 所用的 Google Cloud 專案。
- 確認您已正確導入 API 邏輯 (包含建議的重試策略)。
- 使用這份表單要求提高配額。
系統可能需要一週的時間才能提高 Play Integrity API 配額。因此，強烈建議您透過 Google Play 管理中心或 Google Cloud 控制台監控 Play Integrity API 用量，同時設定配額快訊，以免受到服務中斷影響。
增加的傳統要求配額會自動套用至用戶端與伺服器呼叫，前者用於產生完整性權杖，後者負責解密及驗證。至於增加的標準要求配額，則會套用至伺服器呼叫，以便解密及驗證完整性權杖。
將 Play Integrity API 整合到應用程式中
如要將 Play Integrity API 整合到應用程式或 SDK 中，請根據開發環境採取下列其中一種做法：
Kotlin 或 Java
Google 的 Maven 存放區提供了 Play Integrity API 最新 Android 程式庫。請在應用程式的 build.gradle 檔案中新增以下依附元件：
implementation 'com.google.android.play:integrity:1.4.0'
Unity
請安裝適用於 Unity 的 Google Play Integrity 外掛程式 1.3.0 以上版本。如需操作說明，可參閱這篇文章，瞭解如何安裝適用於 Unity 的 Google 套件。
- 所有 2019.x、2020.x 及後續推出的新版本都在支援範圍內。
- 如果您使用 Unity 2018.x，系統可支援 2018.4 以上版本。
- Unity 2017.x 以下版本不在支援範圍內。
原生
請安裝 Play Core Native SDK 1.13.0 以上版本。如需操作說明，可參閱 Play Core Native 的開發環境設定指南。
設定 API 回應 (選用)
API 回應會包含每個要求傳回的預設判定結果。如果已在 Play 管理中心設定 Play Integrity API 整合功能，就可以自訂 API 回應。
預設回應
根據預設，Play Integrity API 會傳回下列完整性判定結果：
| 回應欄位 | 值 | 說明 |
|---|---|---|
| 裝置完整性 | MEETS_DEVICE_INTEGRITY |
執行應用程式的 Android 裝置是由 Google Play 服務提供支援。該裝置已通過系統完整性檢查，符合 Android 相容性規定。 |
| 空白 (空白值) | 執行應用程式的裝置可能遭受攻擊 (例如掛接 API) 或系統遭到入侵 (例如已啟用 Root 權限)；或者，應用程式不是在實體裝置上執行 (例如未通過 Google Play 完整性檢查的模擬器)。 | |
| Play 帳戶詳細資料 | LICENSED |
使用者擁有應用程式授權。也就是說，使用者是從 Google Play 在裝置上安裝或更新您的應用程式。 |
UNLICENSED |
使用者沒有應用程式授權。這可能是因為使用者側載了您的應用程式，或者不是從 Google Play 取得應用程式。 | |
UNEVALUATED |
由於未符合條件，系統無法評估授權詳細資料。這可能由許多因素造成，包括：
|
|
| 應用程式完整性 | PLAY_RECOGNIZED |
應用程式和憑證符合 Google Play 發行的版本。 |
UNRECOGNIZED_VERSION |
憑證或套件名稱與 Google Play 記錄不符。 | |
UNEVALUATED |
系統無法評估應用程式完整性，原因是未符合必要條件，例如裝置可信度不足。 |
條件式回應
如果將應用程式發行到 Google Play 遊戲電腦版，系統就會自動為您選擇接收裝置完整性判定結果的額外標籤：
| 回應欄位 | 標籤 | 說明 |
|---|---|---|
| 裝置完整性 | MEETS_VIRTUAL_INTEGRITY |
應用程式正在 Google Play 服務支援的 Android Emulator 上執行。該模擬器已通過系統完整性檢查，符合主要的 Android 相容性規定。 |
可選用的回應
如果已在 Play 管理中心或 Play SDK 管理中心設定 Play Integrity API 整合功能，可以選擇在 API 回應中接收資訊。
如要變更 API 回應，請前往 Play 管理中心，依序點選「發布」>「應用程式完整性」，接著在「回應」下方編輯及儲存變更。
可選用的裝置資訊
應用程式和 SDK 可選擇接收裝置完整性判定結果的其他裝置標籤。選擇接收其他標籤後，只要符合個別標籤條件，同一裝置的完整性回應就會包含多個標籤。您可以讓後端伺服器根據可能的回應範圍做出不同處置。例如，相較於只傳回 MEETS_BASIC_INTEGRITY 一個標籤的裝置，傳回 MEETS_STRONG_INTEGRITY、MEETS_DEVICE_INTEGRITY 和 MEETS_BASIC_INTEGRITY 這三個標籤的裝置可能更可信。
您也可以選擇接收近期裝置活動。近期裝置活動會傳回的層級介於 LEVEL_1 (要求數量偏低) 與 LEVEL_4 (要求數量偏高) 之間。舉例來說，如果裝置傳回的活動層級遠高於應用程式一般情況，就可能會嘗試產生大量完整性權杖，發布至不受信任的裝置。
您也可以選擇接收裝置屬性，瞭解裝置上執行的 Android 作業系統的 Android SDK 版本。日後可能會擴充其他裝置屬性。
| 回應欄位 | 標籤 | 說明 | |
|---|---|---|---|
| 裝置完整性 | MEETS_BASIC_INTEGRITY |
執行應用程式的裝置通過了基本系統完整性檢查。該裝置可能不符合 Android 相容性條件，也可能未獲准執行 Google Play 服務。舉例來說，該裝置可能正在執行無法辨識的 Android 版本、已解鎖系統啟動載入程式，或是未經製造商認證。 | |
MEETS_STRONG_INTEGRITY |
執行應用程式的 Android 裝置是由 Google Play 服務提供支援，而且設有硬體支援的開機完整性等措施，足以充分確保系統完整性。該裝置已通過系統完整性檢查，符合 Android 相容性條件。 | ||
| 過去一小時內，每個應用程式在這部裝置上提出的標準 API 完整性權杖要求次數 | 過去一小時內，每個應用程式在這部裝置上提出的傳統 API 完整性權杖要求數量 | ||
| 近期裝置活動 | LEVEL_1 (最低) |
10 部以下 | 5 或少於 5 本 |
LEVEL_2 |
11 到 25 之間 | 6 到 10 之間 | |
LEVEL_3 |
介於 26 到 50 之間 | 11 到 15 歲 | |
LEVEL_4 (最高) |
超過 50 個 | 超過 15 個 | |
UNEVALUATED |
系統未評估近期裝置活動。可能的原因如下：
|
||
| 裝置屬性 | sdkVersion: 19, 20, ..., 35 |
裝置上執行的 Android 作業系統 SDK 版本。傳回的數字會對應至 Build.VERSION_CODES。 |
|
| 空白 (空白值) | 由於未符合必要條件，系統無法評估 SDK 版本。在這種情況下，sdkVersion 欄位未設定，因此 deviceAttributes 欄位為空白。發生這種情況的原因可能包括：
|
||
可選用的環境詳細資料
應用程式可選擇接收額外的環境判定結果。應用程式存取風險功能可讓您瞭解是否有其他可能擷取螢幕截圖、重疊顯示，或控制裝置的應用程式正在執行。Play 安全防護判定結果會指出裝置是否已啟用 Play 安全防護，以及是否發現已知的惡意軟體。
在您選擇接收這些判定結果後，API 回應會包含含有判定結果的環境詳細資料欄位：
| 回應欄位 | 值 | 說明 |
|---|---|---|
| 應用程式存取風險判定結果 | KNOWN_INSTALLED |
應用程式是由 Google Play 安裝，或是裝置製造商在系統分區上預先載入。 |
KNOWN_CAPTURING |
應用程式正在執行中，可用於對提出要求的應用程式 (例如螢幕錄影應用程式) 讀取/擷取輸入和輸出內容。 | |
KNOWN_CONTROLLING |
有 Google Play 安裝的應用程式，或裝置預先載入的應用程式正在執行中，可用於控制提出要求的應用程式 (例如遙控應用程式) 裝置、輸入和輸出內容。 | |
KNOWN_OVERLAYS |
裝置上執行的應用程式是透過 Google Play 安裝或預先載入，可能會在要求的應用程式上顯示疊加層。 | |
UNKNOWN_INSTALLED |
其他應用程式已安裝，並非由 Google Play 安裝，也不是由裝置製造商在系統分區中預先載入。 | |
UNKNOWN_CAPTURING |
其他應用程式正在執行中 (非由 Play 安裝或預先載入至裝置)，可用於讀取或擷取提出要求的應用程式 (例如螢幕錄影應用程式) 輸入和輸出內容。 | |
UNKNOWN_CONTROLLING |
其他應用程式正在執行中 (並非由 Play 安裝或在裝置上預先載入)，可用於控制提出要求的應用程式 (例如遙控應用程式) 裝置、輸入和輸出內容。 | |
UNKNOWN_OVERLAYS |
其他應用程式正在執行 (並非由 Play 安裝或在裝置上預先載入)，可能會在要求的應用程式上顯示重疊層。 | |
| 空白 (空白值) | 如未符合必要條件，系統不會評估應用程式存取風險。在這種情況下，appAccessRiskVerdict 欄位為空白。這可能由許多因素造成，包括：
|
|
| Play 安全防護判定結果 | NO_ISSUES |
已開啟 Play 安全防護，且未在裝置上發現任何應用程式問題。 |
NO_DATA |
已開啟 Play 安全防護，但未執行掃描作業。裝置或 Play 商店應用程式最近可能已重設。 | |
POSSIBLE_RISK |
已關閉 Play 安全防護。 | |
MEDIUM_RISK |
已開啟 Play 安全防護，並發現裝置上安裝了可能有害的應用程式。 | |
HIGH_RISK |
已開啟 Play 安全防護，並發現裝置安裝了危險的應用程式。 | |
UNEVALUATED |
未評估 Play 安全防護判定結果。原因是未符合必要條件，例如裝置可信度不足。 |
調整傳統要求設定 (選用)
如果您只打算提出標準 API 要求，請略過本節步驟。
當您提出傳統要求時，根據預設，Google Play 的伺服器會管理應用程式在您與 Play Integrity API 互動時採用的回應加密方式。我們建議使用這個預設選項，但您也可以按照下方說明，選擇自行管理及下載回應加密金鑰。
讓 Google 管理回應加密方式 (預設和建議選項)
為保障應用程式安全，建議您允許 Google 產生及管理您的回應加密金鑰。您的後端伺服器會呼叫 Google Play 的伺服器來解密回應。
管理及下載我的回應加密金鑰
如果您想在本機安全伺服器環境中解密完整性判定結果，可以自行管理及下載回應加密金鑰。如要管理及下載回應加密金鑰，您必須使用 Play 管理中心，而且除了在任何其他發行管道外，您的應用程式也必須在 Google Play 上架。請按照以下指示，將回應加密金鑰從由 Google 管理改成自行管理。
請記得，切勿在用戶端應用程式中解密或驗證收到的權杖，也不要將解密金鑰提供給用戶端應用程式。
請務必先確認您的伺服器已正確設定，可以在本機或在 Google Play 伺服器上解密及驗證完整性權杖，之後再前往 Play 管理中心變更回應加密管理策略，以免受到服務中斷影響。
改成由 Google 管理或自行管理回應加密金鑰
如果目前由 Google 管理回應加密作業，但您想改成自行管理並下載回應加密金鑰，請按照下列步驟操作：
- 登入 Play 管理中心。
- 選取使用 Play Integrity API 的應用程式。
- 在左選單的「版本」部分，前往「應用程式完整性」。
- 按一下「Play Integrity API」旁邊的「設定」。
- 在頁面上的「傳統要求」部分，按一下「回應加密設定」旁邊的「編輯」。
- 在隨即顯示的視窗中，按一下「管理及下載我的回應加密金鑰」。
- 按照操作說明上傳公開金鑰。
- 當視窗顯示上傳成功後，按一下「儲存」，系統就會自動下載加密金鑰。
- 變更伺服器邏輯，讓系統透過您的回應加密金鑰，在本機安全伺服器環境中解密及驗證完整性權杖。
- (選用) 如果您自行管理回應加密金鑰，您的應用程式仍可改回由 Google Play 伺服器解密及驗證回應。
如果您是自行管理回應加密金鑰，但希望改為讓 Google 管理回應加密方式，請按照下列步驟操作：
- 變更伺服器邏輯，改成只在 Google 伺服器上進行解密及驗證。
- 登入 Play 管理中心。
- 選取使用 Play Integrity API 的應用程式。
- 在左選單的「版本」部分，前往「應用程式完整性」。
- 按一下「Play Integrity API」旁邊的「設定」。
- 在頁面上的「傳統要求」部分，按一下「回應加密設定」旁邊的「編輯」。
- 在隨即顯示的視窗中，點選「讓 Google 管理我的回應加密設定 (建議)」。
- 按一下「Save changes」。