設定

本頁面說明如何設定應用程式或遊戲來使用 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 管理中心啟用 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 個要求。如果應用程式需要處理更多使用者，可以按照以下說明，要求提高每日上限。

動作 每個應用程式的每日配額 附註
權杖要求 10,000 傳統要求和標準權杖準備作業共用
在 Google 伺服器上解密權杖 10,000 傳統和標準要求共用

調高每日要求數量上限

除了在任何其他發行管道外，您的應用程式也必須在 Google Play 上架，這樣您才有資格申請調高每日的要求數量上限。即使每日上限已上調，您仍應繼續將每位使用者的傳統要求限制為不常執行的重要操作，以便保留使用者資料和電池電力。

如要申請調高每日要求數量上限，請完成下列操作：

  1. 在 Play 管理中心連結 Play Integrity API 所用的 Google Cloud 專案。
  2. 確認您已正確導入 API 邏輯 (包含建議的重試策略)。
  3. 使用這份表單要求提高配額。

系統可能需要一週的時間才能提高 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 API，涵蓋支援的 Unity 版本、安裝方法和環境設定。

支援的 Unity 版本

  • 所有 2019.x、2020.x 及後續推出的新版本都在支援範圍內。
  • 如果您使用 Unity 2018.x，系統可支援 2018.4 以上版本。
  • Unity 2017.x 以下版本不在支援範圍內。

設定開發環境

OpenUPM-CLI

如果您已安裝 OpenUPM CLI，可以使用下列指令安裝 OpenUPM 登錄檔：

openupm add com.google.play.integrity

OpenUPM

  1. 選取 Unity 選單選項「Edit」>「Project Settings」>「Package Manager」，開啟套件管理工具設定。

  2. 在「Package Manager」視窗中，將 OpenUPM 新增為範圍登錄檔：

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.integrity

  3. 選取 Unity 選單選項「Window」>「Package Manager」，開啟套件管理工具選單。

  4. 將管理員範圍下拉式選單設為選取「我的登錄」。

  5. 從套件清單中選取「Google Play Integrity plugin for Unity」套件，然後按下「Install」。

從 GitHub 匯入

  1. 從 GitHub 下載最新 .unitypackage 版本。

  2. 依序選取 Unity 選單選項「Assets」>「Import package」>「Custom Package」，然後匯入所有項目，即可匯入 .unitypackage 檔案。

Unreal Engine

以下各節說明如何整合及設定 Unreal Engine 專案的 Google Play Integrity API。

支援的 Unreal Engine 版本

外掛程式支援 Unreal Engine 5.0 和所有後續版本。

設定開發環境

  1. 從 GitHub 存放區下載 Play Unreal Engine 外掛程式。

  2. 複製 Unreal Engine 專案中 Plugins 資料夾內的 GooglePlay 資料夾。

  3. 開啟 Unreal Engine 專案，然後依序點選「Edit」→「Plugins」。

  4. 搜尋「Google Play」，然後勾選「已啟用」核取方塊。

  5. 重新啟動遊戲專案並觸發建構作業。

  6. 開啟專案的 Build.cs 檔案，並將 PlayIntegrity 模組新增至 PublicDependencyModuleNames：

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayIntegrity");

    // ...
  }
}

原生

請安裝 Play Core Native SDK 1.13.0 以上版本。如需操作說明，請參閱 Play Core Native 的開發環境設定指南。

設定 API 回應 (選用)

API 回應會包含每個要求傳回的預設判定結果。如果已在 Play 管理中心設定 Play Integrity API 整合功能，就可以自訂 API 回應。

預設回應

根據預設，Play Integrity API 會傳回下列完整性判定結果：

回應欄位 值 說明
裝置完整性 MEETS_DEVICE_INTEGRITY 應用程式正在通過 Play 安全防護認證的 Android 正版裝置上執行。在 Android 13 以上版本中，系統會提供硬體支援的證明，指出裝置的系統啟動載入程式已鎖定，且載入的 Android 作業系統是經過認證的裝置製造商映像檔。
空白 (空白值) 執行應用程式的裝置可能遭受攻擊 (例如掛接 API) 或系統遭到入侵 (例如已啟用 Root 權限)；或者，應用程式不是在實體裝置上執行 (例如未通過 Google Play 完整性檢查的模擬器)。
Play 帳戶詳細資料 LICENSED 使用者擁有應用程式授權。也就是說，使用者在裝置上從 Google Play 安裝或更新您的應用程式。
UNLICENSED 使用者沒有應用程式授權。這可能是因為使用者側載了您的應用程式，或者不是從 Google Play 取得應用程式。
UNEVALUATED 由於未符合條件，系統無法評估授權詳細資料。這可能由許多因素造成，包括：
  • 裝置可信度不足。
  • 使用者未登入 Google Play。
  • Google Play 無法辨識裝置上安裝的應用程式版本。
應用程式完整性 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 這三個標籤的裝置可能更可信。

您可以選擇接收裝置屬性，瞭解裝置上執行的 Android 作業系統的 Android SDK 版本。日後可能會擴充其他裝置屬性。

你可以選擇接收近期裝置活動資訊。近期裝置活動會傳回 LEVEL_1 (要求數量偏低) 到 LEVEL_4 (要求數量偏高) 之間的層級。舉例來說，如果裝置傳回的活動層級遠高於應用程式一般情況，就可能嘗試產生大量完整性權杖，發布至不受信任的裝置。

應用程式也可以選擇加入裝置召回計畫。裝置喚回功能可讓您在特定裝置上儲存一些自訂的裝置專屬資料，並在稍後於同一部裝置上重新安裝應用程式時，穩定地擷取這些資料。

選擇接收選用的裝置資訊和裝置召回資訊後，API 回應的判定結果會包含新的裝置完整性欄位和回應：

回應欄位 標籤 說明
裝置完整性 MEETS_BASIC_INTEGRITY 應用程式會在通過基本系統完整性檢查的裝置上執行。裝置的系統啟動載入程式可以鎖定或解鎖，啟動狀態可以是已驗證或未驗證。裝置可能未通過 Play 安全防護認證，因此 Google 無法提供任何安全性、隱私權或應用程式相容性保證。在 Android 13 以上版本中，MEETS_BASIC_INTEGRITY 判定結果必須由 Google 提供認證 信任根。
MEETS_STRONG_INTEGRITY 應用程式是在通過 Play 安全防護認證的正版 Android 裝置上執行，且裝置已安裝最新的安全性更新。
  • 在 Android 13 以上版本中，MEETS_STRONG_INTEGRITY判決結果要求裝置的所有分割區 (包括 Android 作業系統分割區修補程式和供應商分割區修補程式) 必須在過去一年內收到 MEETS_DEVICE_INTEGRITY 和安全性更新。
  • 在 Android 12 以下版本中，MEETS_STRONG_INTEGRITY 判決結果只需要硬體支援的開機完整性證明，不需要裝置具備最新的安全性更新。因此，使用 MEETS_STRONG_INTEGRITY 時，建議一併考量 deviceAttributes 欄位中的 Android SDK 版本。
裝置屬性 sdkVersion: 19, 20, ..., 36 裝置上執行的 Android 作業系統 SDK 版本。 傳回的數字會對應至 Build.VERSION_CODES。
空白 (空白值) 由於未符合必要條件，系統不會評估 SDK 版本。在本例中，sdkVersion 欄位未設定，因此 deviceAttributes 欄位為空白。可能原因如下：
  • 裝置可信度不足。
  • 裝置發生技術問題。
過去一小時內，每款應用程式在這部裝置上提出的標準 API 完整性權杖要求 過去一小時內，這部裝置上每個應用程式的傳統 API 完整性權杖要求
近期裝置活動 LEVEL_1 (最低) 10 部以下 5 或少於 5 本
LEVEL_2 11 到 25 個 6 到 10
LEVEL_3 26 到 50 歲 11 到 15
LEVEL_4 (最高) 超過 50 個 超過 15 個
UNEVALUATED 系統未評估近期裝置活動。可能的原因如下：
  • 裝置可信度不足。
  • Google Play 無法辨識裝置上安裝的應用程式版本。
  • 裝置發生技術問題。
裝置喚回 values: bitFirst, bitSecond, bitThird 這些是您過去為特定裝置設定的位元值。您可以決定每個位元代表的意義。這三個位元值預設為 false。
writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird 這些是世界標準時間的位元值寫入日期，精確度達年和月。每當召回位元設為 true 時，系統就會更新寫入日期；位元設為 false 時，系統則會移除寫入日期。

可選用的環境詳細資料

應用程式可選擇接收額外的環境判定結果。 應用程式存取風險會指出是否有其他執行中的應用程式可能在擷取螢幕畫面、重疊顯示或操控裝置。「Play 安全防護判定」會指出裝置是否已啟用 Play 安全防護，以及是否發現已知惡意軟體。

選擇接收這些判定結果後，API 回應會包含含有判定結果的環境詳細資料欄位：

回應欄位 值 說明
應用程式存取風險判定結果 KNOWN_INSTALLED 應用程式是由 Google Play 安裝，或是裝置製造商在系統分區上預先載入。
KNOWN_CAPTURING 裝置上正在執行透過 Google Play 安裝或預先載入的應用程式，可用於讀取或擷取提出要求的應用程式 (例如螢幕錄影應用程式) 的輸入和輸出內容。
KNOWN_CONTROLLING 有透過 Google Play 安裝或預先載入的應用程式正在執行中，可用於控制裝置，以及提出要求的應用程式的輸入和輸出內容，例如遙控應用程式。
KNOWN_OVERLAYS 裝置上正在執行透過 Google Play 安裝或預先載入的應用程式，可能會在要求存取權的應用程式上顯示重疊畫面。
UNKNOWN_INSTALLED 其他應用程式已安裝，並非由 Google Play 安裝，也不是由裝置製造商在系統分區中預先載入。
UNKNOWN_CAPTURING 其他應用程式正在執行中 (並非由 Play 安裝或預先載入至裝置)，可用於對提出要求的應用程式 (例如螢幕錄影應用程式) 讀取/擷取輸入和輸出內容。
UNKNOWN_CONTROLLING 其他應用程式正在執行中 (並非由 Play 安裝或預先載入至裝置)，可用於控制提出要求的應用程式 (例如遙控應用程式) 裝置、輸入和輸出內容。
UNKNOWN_OVERLAYS 其他應用程式正在執行 (並非由 Play 安裝或預先載入至裝置)，可能會在提出要求的應用程式上顯示重疊畫面。
空白 (空白值) 如果未符合必要條件，系統不會評估應用程式存取風險。在本例中，appAccessRiskVerdict 欄位為空白。這可能由許多因素造成，包括：
  • 裝置可信度不足。
  • 裝置板型規格不是手機、平板電腦或折疊式裝置。
  • 裝置未搭載 Android 6 (API 級別 23) 以上版本。
  • Google Play 無法辨識裝置上安裝的應用程式版本。
  • 裝置上的 Google Play 商店版本過舊。
  • 僅限遊戲：使用者帳戶沒有遊戲的 Play 授權。
  • 使用標準要求搭配 verdictOptOut 參數。
  • 您使用的 Play Integrity API 程式庫版本不支援標準要求的應用程式存取風險，因此提出標準要求。
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 管理回應加密作業，但您想改成自行管理並下載回應加密金鑰，請按照下列步驟操作：

  1. 登入 Play 管理中心。
  2. 選取使用 Play Integrity API 的應用程式。
  3. 在左選單的「版本」部分，前往「應用程式完整性」。
  4. 按一下「Play Integrity API」旁邊的「設定」。
  5. 在頁面上的「傳統要求」部分，按一下「回應加密設定」旁邊的「編輯」。
  6. 在隨即顯示的視窗中，按一下「管理及下載我的回應加密金鑰」。
  7. 按照操作說明上傳公開金鑰。
  8. 當視窗顯示上傳成功後，按一下「儲存」，系統就會自動下載加密金鑰。
  9. 變更伺服器邏輯，讓系統透過您的回應加密金鑰，在本機安全伺服器環境中解密及驗證完整性權杖。
  10. (選用) 如果您自行管理回應加密金鑰，您的應用程式仍可改回由 Google Play 伺服器解密及驗證回應。

如果您是自行管理回應加密金鑰，但希望改為讓 Google 管理回應加密方式，請按照下列步驟操作：

  1. 變更伺服器邏輯，改成只在 Google 伺服器上進行解密及驗證。
  2. 登入 Play 管理中心。
  3. 選取使用 Play Integrity API 的應用程式。
  4. 在左選單的「版本」部分，前往「應用程式完整性」。
  5. 按一下「Play Integrity API」旁邊的「設定」。
  6. 在頁面上的「傳統要求」部分，按一下「回應加密設定」旁邊的「編輯」。
  7. 在隨即顯示的視窗中，點選「讓 Google 管理我的回應加密設定 (建議)」。
  8. 按一下「Save changes」。
上一頁
總覽
下一頁
執行標準要求