本頁面由 Cloud Translation API 翻譯而成。

新增 Play Integrity API

藉由電腦版 Play Integrity API，您可以檢查互動情形和伺服器要求，確認來源是正版電腦裝置。偵測具有潛在風險的詐欺活動後，應用程式的後端伺服器就能採取適當的因應措施，防範攻擊並減少濫用情形。

API 會傳回判定結果，協助您偵測潛在威脅，包括：

有風險的裝置和環境：deviceIntegrity 判定結果可協助您判斷應用程式是否在正版電腦裝置上執行，或在正規的 Google Play 遊戲電腦版中執行。

整合 API

如要將電腦版 Play Integrity API 整合至應用程式，請先在 Google Cloud 控制台中完成初始設定。接著，您需要針對每項完整性檢查執行下列步驟：

準備完整性權杖
要求完整性權杖
要求權杖資料

在 Google Cloud 控制台中完成初始設定

凡是會呼叫 Play Integrity API 的應用程式或 SDK，都必須使用 Google Cloud 專案驗證呼叫，並監控 API 用量。如果您想建立新的 Cloud 專案，或只在 Google Play 以外的管道發行應用程式，可以透過 Google Cloud 控制台啟用 Play Integrity API 回應。

請在 Google Cloud 控制台中建立新的 Cloud 專案，或選擇要搭配電腦版 Play Integrity API 使用的現有 Cloud 專案。接著前往「API 和服務」，選取「啟用 API 和服務」，搜尋「Play Integrity API」，然後啟用該 API。完成後，即可將 Play Integrity API 整合到應用程式中。

步驟 1：準備完整性權杖

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

要求完整性權杖 (請參閱「RequestIntegrityToken」) 之前，您必須先備妥 Play Integrity API，這也稱為「暖機」程序。如此一來，Google Play 就能靈敏地在裝置上快取部分認證資訊，進而在您索取完整性判定結果時，縮短關鍵路徑上的延遲時間。

成功時，系統會使用包含 RequestTokenData 的 PrepareIntegrityTokenResultValue 呼叫續傳，該資料應做為要求完整性權杖的依據。這項資料應快取在記憶體中，並在應用程式工作階段期間重複使用，以呼叫 RequestIntegrityToken。只有在應用程式判斷有必要完全重新評估完整性判定結果時，才應呼叫 PrepareIntegrityToken。

詳細說明
參數	`params`：包含 Google Cloud 專案編號的參數。 `continuation`：要將完整性權杖供應工具傳回的非同步回呼。

步驟 2：要求完整性權杖

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

完整性權杖是應用程式用來驗證裝置未遭竄改的機制。舉例來說，後端伺服器可以使用完整性權杖驗證下列事項：

正版裝置：判斷應用程式是否在含有正規 Google Play 遊戲電腦版且未遭竄改的正版裝置上執行。

使用 Play Integrity API 檢查電腦版應用程式中的使用者動作時，您可以利用 RequestIntegrityTokenParams::request_hash 欄位應對竄改攻擊。舉例來說，遊戲可能要向遊戲後端伺服器回報玩家分數，而您的伺服器想驗證 Proxy 伺服器未竄改分數，在此情況下，就適合使用上述欄位。Play Integrity API 會在已簽署的完整性回應內，傳回您在這個欄位中設定的值。如果沒有 requestHash，完整性權杖就只會繫結至裝置，而不會繫結至特定要求，因此可能遭受攻擊。

如要在要求完整性判定結果時減輕這項影響，請完成下列操作：

從正在發生的使用者動作或伺服器要求中，計算所有相關要求參數的摘要 (例如穩定要求序列化的 SHA256)。
將 RequestIntegrityTokenParams::request_hash 欄位設為摘要。

詳細說明
參數	`params`：包含準備好的 RequestTokenData 和完整性檢查要求雜湊的參數。 `continuation`：非同步回呼，用於傳回資料。

步驟 3：要求權杖資料

您索取完整性判定結果後，Play Integrity API 會提供已加密的回應權杖。您必須在 Google 伺服器上解密完整性權杖，才能取得裝置完整性判定結果。如要啟用這項功能，請完成下列步驟：

在連結至應用程式的 Google Cloud 專案中建立服務帳戶。

在應用程式伺服器上，使用 playintegrity 範圍從服務帳戶憑證中擷取存取權杖，然後提出下列要求：

playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
 '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'

讀取 JSON 回應。

產生的酬載是包含完整性判定結果和詳細資料的純文字權杖，以及開發人員提供的資訊。權杖格式如下：

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

您必須先檢查 requestDetails 欄位中的值是否與原始要求的值相符，再逐一檢查完整性判定結果。以下章節會詳細介紹各個欄位。

要求詳情欄位

requestDetails 欄位包含要求的相關資訊，包括開發人員在標準要求的 requestHash 和傳統要求的 nonce 中提供的資訊

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

這些值應與原始要求的值相符。因此，請確認 requestPackageName 和 requestHash 與原始要求中傳送的值相符，藉此驗證 JSON 酬載的 requestDetails 部分。

裝置完整性欄位

deviceIntegrity 欄位可包含單一值 deviceRecognitionVerdict，後者包含一或多個標籤，代表裝置可強制執行應用程式完整性檢查的程度。如果裝置不符合任何標籤的條件，deviceIntegrity 欄位就會省略 deviceRecognitionVerdict。

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

根據預設，deviceRecognitionVerdict 可包含下列項目：

MEETS_PC_INTEGRITY: 如果應用程式在正版電腦環境中執行，且系統未偵測到裝置端竄改行為，則會傳回判定結果。
空白 (空白值): 執行應用程式的裝置可能遭受攻擊 (例如掛接 API) 或系統遭到入侵 (例如已啟用 Root 權限)；或者，應用程式不是在實體裝置上執行 (例如未通過 Google Play 完整性檢查的模擬器)。

使用限制

Play Integrity API 用量限制

每個應用程式每天最多總共只能提出 10,000 個要求。如果應用程式需要處理更多使用者，可以按照以下說明，要求提高每日上限。

動態	每個應用程式的每日配額	注意事項
權杖要求	10,000	適用於電腦版 Play Integrity API，以及 Play Integrity API 的傳統和標準要求
在 Google 伺服器上解密權杖	10,000	適用於電腦版 Play Integrity API，以及 Play Integrity API 的傳統和標準要求

調高每日要求數量上限

除了在任何其他發行管道外，您的應用程式也必須在 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 在與其他信號搭配使用，也就是做為整體反濫用策略的一部分，而非單一反濫用機制時效用最佳。在應用程式使用這個 API 的同時，也請搭配其他適當的安全性最佳做法。根據預設，應用程式每天在所有安裝檔中最多共可提出 10,000 次要求，但您可以要求提高每日上限。

收集遙測資訊及瞭解目標對象，再採取行動

在根據 Play Integrity API 判定結果變更應用程式行為之前，您可以透過不強制執行的方式實作 API，瞭解現有目標對象的目前情況。瞭解目前的安裝數會傳回什麼判定結果後，您就可以預估自己規劃的強制執行作業有何影響，再據此調整反濫用策略。

在適當時機要求系統提供完整性判定結果

您應盡可能在執行動作或伺服器要求時，提出 API 要求。

避免他人輕易複製您的 API 要求

API 要求中有一個名為 requestHash 的欄位，用於防範竄改和類似攻擊。在這個欄位中，您應加入應用程式要求內所有相關值的摘要。請按照如何使用內容繫結指南操作，為應用程式的標準要求提供防護。

避免快取完整性判定結果

快取完整性判定結果會增加處理 Proxy 的風險，在 Proxy 這類攻擊中，不肖人士會在另一個環境重複使用善意裝置的判定結果，為的就是要大肆濫用。

從伺服器將一系列回應傳送至應用程式

與其每次都將相同的二進位檔成功 / 失敗回應從伺服器傳回應用程式，不妨提供一系列決策結果，因為這樣可增加複製難度。例如，您可以使用一系列相關的回應，像是「允許」、「允許限制」、「在人機驗證 (Captcha) 完成後允許限制」，以及「拒絕」。

顯示可採取行動的錯誤訊息

請盡可能為使用者提供實用的錯誤訊息，並告知應採取哪些行動來修正問題。

因應非預期狀況或服務中斷

Play 狀態資訊主頁會顯示 Play Integrity API 服務狀態的相關資訊，以及所有停止運作和服務中斷相關資訊。建議您預先規劃萬一發生大規模 Play Integrity API 服務中斷情形時，後端伺服器該如何運作。

服務條款與資料安全性

存取或使用電腦版 Play Integrity API，即表示您同意《Play Integrity API 服務條款》。存取 API 前，請詳閱並瞭解所有適用的條款和政策。

Google Play 提供了「資料安全性」專區，可讓開發人員揭露應用程式的資料收集、分享和安全性做法，讓使用者掌握相關資訊。為協助您填寫資料表單，請參閱這裡的資訊，瞭解 Play Integrity API 如何處理資料。