このページは Cloud Translation API によって翻訳されました。

Play Integrity API を追加する

PC 向け Play Integrity API を使用すると、操作やサーバーリクエストが正規の PC デバイスから行われたものかどうかを確認できます。危険性のある不正な操作を検出することで、アプリのバックエンドサーバーで、攻撃を防ぎ不正使用を減らすための適切な措置を講じることができます。

この API は、次のような潜在的な脅威の検出に役立つ判定結果を返します。

危険なデバイスと環境: deviceIntegrity 判定は、アプリが正規の PC デバイスまたは PC 版 Google Play Games の正規のインスタンスで実行されているかどうかを判断するのに役立ちます。

API と統合する

PC 向け 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 プロジェクトを作成するか、PC 版 Play Integrity API で使用する既存の Cloud プロジェクトを選択します。[API とサービス] に移動します。[API とサービスの有効化] を選択します。Play Integrity 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
)

完全性トークンは、デバイスが改ざんされていないことをアプリケーションが確認するためのメカニズムです。たとえば、バックエンドサーバーは完全性トークンを使用して次のことを確認できます。

正規のデバイス: アプリケーションが、改ざんされていない PC 版 Google Play Games の正規のインスタンスを含む正規のデバイスで実行されているかどうかを判定します。

PC 向け Play Integrity API を使用してアプリ内のユーザーアクションをチェックする場合は、RequestIntegrityTokenParams::request_hash フィールドを使用して改ざん攻撃を軽減できます。たとえば、プレーヤーのスコアをゲームのバックエンドサーバーにレポートするゲームで、プロキシサーバーによってスコアが改ざんされていないことを確認したい場合があります。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 という値のみが含まれます。この値には、デバイスがアプリの完全性をどの程度強化できるかを表すラベルが 1 つ以上含まれています。デバイスがラベルの基準を満たしていない場合、deviceIntegrity フィールドは deviceRecognitionVerdict を省略します。

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

デフォルトでは、deviceRecognitionVerdict に含めることができる値は以下のとおりです。

MEETS_PC_INTEGRITY: アプリが真正な PC 環境で実行されており、デバイス上の改ざんが検出されなかった場合、判定結果を返します。
空（空の値）: アプリは、API フックなどの攻撃や root 権限取得などのシステム侵害の兆候があるデバイス、または Google Play の完全性チェックに合格していない仮想デバイス（エミュレータなど）で動作しています。

使用量上限

Play Integrity API の使用制限

アプリごとに 1 日あたり最大 10,000 件のリクエスト上限が適用されます。アプリが増加するユーザー数に対応する必要がある場合は、以下の手順で 1 日あたりの上限の引き上げをリクエストできます。

操作	アプリごとの 1 日の割り当て	注意事項
トークンリクエスト	10,000	PC 版 Play Integrity API と、クラシックリクエストおよび標準リクエスト用の Play Integrity API で共有されます。
Google のサーバーでのトークンの復号	10,000	PC 向け Play Integrity API と、クラシックリクエストおよび標準リクエスト向け Play Integrity API で共有されます。

リクエストの 1 日あたりの上限を引き上げる

リクエストの 1 日あたりの上限を引き上げるには、他の配信チャネルに加えて Google Play でもアプリが利用できる必要があります。

リクエスト数の 1 日あたりの上限の引き上げをリクエストする手順は次のとおりです。

Google Play Console で、Play Integrity API に使用している Google Cloud プロジェクトをリンクします。
推奨される再試行戦略などの API ロジックを正しく実装していることを確認します。
こちらのフォームを使用して、割り当ての増加をリクエストします。

Play Integrity API の割り当ての引き上げには、最長で 1 週間かかることがあります。そのため、Google Play Console または Google Cloud コンソールで Play Integrity API の使用量をモニタリングすることを強くおすすめします。これらのコンソールでは、サービスが中断されることがないように、割り当てアラートをセットアップすることもできます。

割り当てが増えると、完全性トークンを生成するクライアント呼び出しと、完全性トークンの復号と検証を行うサーバー呼び出しの両方に自動的に適用されます。

セキュリティ上の考慮事項

Play Integrity API は、以下のおすすめの方法を実践すると、アプリで最大限の効果を発揮します。

不正使用対策戦略を準備する

Play Integrity API は、単独の不正使用対策メカニズムとして使用するのでなく、不正使用対策戦略の一環として他のシグナルと併用すると、最大限の効果を発揮します。この API は、アプリに適した他のセキュリティに関するおすすめの方法と組み合わせて使用してください。デフォルトでは、アプリはすべてのインストールで 1 日あたり最大 10,000 件のリクエストを実行できます。ただし、1 日あたりの上限の引き上げをリクエストできます。

アクションの前にテレメトリーを収集し対象ユーザーを理解する

Play Integrity API の判定結果に基づいてアプリの動作を変更する前に、まず API を適用せずに実装することで既存のユーザー層の現状を把握できます。現在のインストールベースの判定結果が判明したら、計画している適用を実施した場合の影響を推定し、それに応じて不正使用対策戦略を調整できます。

適切なタイミングで完全性判定の結果をリクエストする

API リクエストは、保護するアクションやサーバーリクエストにできるだけ近いタイミングで行う必要があります。

API リクエストの複製を困難にする

API リクエストには requestHash というフィールドがあり、改ざんやその種の攻撃を防ぐために使用できます。このフィールドには、アプリのリクエストに関連するすべての値のダイジェストを含める必要があります。アプリの標準リクエストを保護するには、コンテンツバインディングの使用方法のガイダンスをご覧ください。

完全性判定の結果をキャッシュに保存しない

完全性判定の結果をキャッシュに保存すると、プロキシ攻撃のリスクが高くなります。これは、不正な行為者が不正な目的で別の環境から真正なデバイスの判定結果を再利用する攻撃です。

サーバーからアプリに多様なレスポンスを送信する

多様な決定結果を用意すると、各レスポンスでサーバーからアプリにバイナリの許可または拒否のレスポンスを送信するよりも、複製が困難になります。たとえば、「許可」、「制限付きで許可」、「CAPTCHA の完了後に制限付きで許可」、「拒否」のような一連の関連するレスポンスを使用できます。

実用的なエラーメッセージを表示する

可能であれば、有用なエラーメッセージをユーザーに提供して、問題を自ら解決できるようにします。

不測の問題や障害に対する計画を立てる

Play ステータスダッシュボードには、Play Integrity API のサービスのステータスに関する情報に加えて、停止や障害に関する情報も表示されます。Play Integrity API で万が一大規模な障害が起きた場合に備えて、バックエンドサーバーの動作を事前に計画する必要があります。

利用規約とデータセーフティ

PC 向け Play Integrity API にアクセスするか、またはこれを使用すると、Play Integrity API 利用規約に同意したことになります。API にアクセスする前に、適用されるすべての利用規約とポリシーを確認し、理解してください。

Google Play には、デベロッパーがアプリによるデータの収集、データの共有、アプリのセキュリティ対策を開示し、ユーザーに最新情報を提供するためのデータセーフティセクションがあります。データフォームの記入方法については、Play Integrity API によるデータ処理の仕組みに関する情報をご覧ください。