KappSナレッジベース · ブログ

2026年のGoogle PlayIntegrity API:ステップバイステップガイド

ブログ ガイド

Play Integrity APIは、バックエンドにとって狭く実用的な問いに答えます。このリクエストは、Google Playが出荷した自分のアプリのコピーから、名乗るとおりのデバイス上で送信されているのか、という問いです。サーバーはGoogleにインテグリティ判定を要求し、署名済みペイロードを受け取り、そのやり取りをどこまで信頼するかをクライアント側ではなく必ずサーバー側で決定します。改ざんされたビルド、スクリプト化されたクライアント、エミュレーター、サイドロードされたコピーが、ゲーム経済、サブスクリプションの権利、広告収益に到達する前に食い止める標準的な方法です。

このガイドは、実際に作業する順序に沿って進みます。APIを有効化し、Cloudプロジェクトをリンクし、標準リクエストとクラシックリクエストのどちらかを選び、トークンプロバイダーをウォームアップし、トークンをリクエストして復号し、判定フィールドを読み取り、クォータとエラーコードを処理し、有料ユーザーを締め出さずに執行を段階的に展開します。すべてに通底する原則が一つあります。APIが渡すのは自分で判断するためのシグナルであり、整合性チェックを確実に通過する唯一の方法は、正規のチャネルを通じて本物のアプリをリリースすることです。


1. APIが証明するもの、しないもの

判定はデフォルトで3つの系統に分かれて返ってきて、それぞれが異なる問いに答えるものです。

  • appIntegrity — これは改変されていないあなたのバイナリから来たものか? appRecognitionVerdictは、パッケージと証明書がGoogle Playの配布内容と一致すればPLAY_RECOGNIZEDを、証明書またはパッケージ名がPlayの記録と一致しなければUNRECOGNIZED_VERSIONを、前提条件が満たされなかった場合はUNEVALUATEDを返します。
  • deviceIntegrity — 端末は正規か? デフォルトではdeviceRecognitionVerdictにMEETS_DEVICE_INTEGRITYが含まれることがあります。これは正規の認定Android端末で、Android 13以降ではブートローダーがロックされ、読み込まれたソフトウェアが正規であることをハードウェアで裏付けます。どのラベルにも該当しない端末では、単にこのフィールドが省略されます。
  • accountDetails — ユーザーは購入権利を保有しているか? appLicensingVerdictはLICENSED(Google Playからインストールまたは更新済み)、UNLICENSED、またはUNEVALUATEDを返します。

フィールドの一覧よりも重要な、2つの規律があります。第一に、GoogleはAPIが他のシグナルと併用して機能することを明確に述べており、不正対策全体の戦略の一部として使うものであって、唯一の仕組みではありません。判定は1つの入力にすぎず、それを唯一の関門とすると、誤検知と容易な回避の両方を生みます。第二に、これらはリスクのシグナルであり、ユーザーへの評価ではありません。ルート化された端末を使う趣味のユーザーは犯罪者ではなく、対応はその画面で実際に何が危険にさらされているかに比例すべきです。

2. ステップ1 — APIを有効化し、Cloudプロジェクトをリンクする

APIを呼び出すすべてのアプリやSDKにはGoogle Cloudプロジェクトが必要です。利用状況の監視とクォータの管理はそこで行われるためです。

  1. Google Cloud Consoleで、新しいプロジェクトを作成するか、使用する既存のプロジェクトを選択します。
  2. APIとサービス → APIとサービスを有効にするに進み、Play Integrity APIを検索して有効にするをクリックします。
  3. 次にそのプロジェクトをアプリにリンクします。Play Consoleでアプリを開き、Protected with Playに進み、Play Integrity APIを見つけて始めるを選択します。

リンク設定こそが、その他すべてを可能にするステップです。Cloudで有効化されていてもPlay Console(SDKの場合はPlay SDK Console)でリンクされていないプロジェクトは、追加の設定オプションや割り当て増加の対象になりません。コンソールの手順を飛ばしていても、リンクのフローがAPIを有効化してくれるので、どちらの順序でも問題ありません。リンクを飛ばすことだけは許されません。

復号には、アプリが決して保持してはならない認証情報が必要です。リンク済みのCloudプロジェクト内にサービスアカウントを作成し、playintegrityスコープでサーバーからデコードエンドポイントを呼び出します。クライアントはトークンを要求するだけで、開くのはサーバーだけです。

3. ステップ2 — 標準リクエストかクラシックリクエストを選ぶ

リクエストには2つのスタイルがあり、最初に正しい方を選べば後の書き直しを避けられます。

  • 標準リクエストは、Google Play上のアプリにとって既定の選択肢です。Android 5.0(APIレベル21)以上で動作し、2つの呼び出しで構成されます。あらかじめインテグリティトークンプロバイダを準備し、実際にトークンが必要になった時点でリクエストします。
  • クラシックリクエストは、標準リクエストでは対応できないケース、とくにGoogle Play以外でのみ配布されるアプリやSDK向けに存在します。構造上、クラシックリクエストは生成したナンスを受け取る単一の呼び出しで、Playで配布されないアプリはsetCloudProjectNumber()でCloudプロジェクト番号も渡す必要があります。Play上のアプリはコンソールで紐付けられるため、リクエスト内で設定しません。

アプリがGoogle Playで配信されているなら、standardが正解です。classicを選ぶのは、配信が本当にPlay外で行われる場合か、特定の連携によって制約を受ける場合だけです。

4. ステップ3 — プロバイダをウォームアップしてからトークンをリクエストする

標準的なリクエストは意図的に2つに分割され、遅い部分がユーザーのクリティカルパスに乗らないようになっています。

整合性トークンプロバイダーを準備(ウォームアップ)します。判定が必要になるずっと前に呼び出してください。通常はアプリ起動時が適しており、呼び出しは非同期で起動時間に影響しないためうまく機能します。ウォームアップにより、Google Playは部分的なアテステーション情報をデバイスにキャッシュできるため、後続のリクエストが高速になります。再準備は、次の判定をより最新にする軽量な方法でもあります。プロバイダー自体は長く保持しすぎると期限切れになり、INTEGRITY_TOKEN_PROVIDER_INVALIDとして現れます。その場合は古いプロバイダーを再試行するのではなく、新しいプロバイダーを要求して対処してください。

必要に応じて整合性トークンをリクエストします。アプリが保証したいサーバー呼び出しを行う際は、トークンをリクエストしてバックエンドに送信します。リクエストハッシュを付加してください。安定したパラメータのSHA-256などでダイジェストを計算して渡します。APIは署名済みレスポンス内でその値をそのまま返すためです。これがないと、トークンはデバイスに紐づいても特定のリクエストには紐づかず、まさにその隙間を突いてプロキシが別の用途に再利用できてしまいます。

クラシックリクエストでは、代わりにご自身で用意したnonceを使用します。これはそのままGoogleに渡されるため、個人情報や機密情報は絶対に含めないでください。また、許容される長さの有効なBase64である必要があります。そうでない場合、判定結果ではなくNONCE_TOO_SHORT、NONCE_TOO_LONG、またはNONCE_IS_NOT_BASE64が返されます。

5. ステップ4 — サーバー側で復号して検証する

バックエンドに届くトークンは暗号化されており、Googleが復号するまで役に立ちません。サービスアカウントの認証情報とplayintegrityスコープを使って、サーバーが呼び出します:

POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }

返ってくるのはプレーンテキストのJSONペイロードです。判定を1つ見る前に、リクエストの詳細を検証してください。ペイロードは、本当にあなたのリクエストへの応答である場合にのみ意味を持つからです:

  • requestPackageNameはパッケージ名と一致している必要があります。
  • requestHashは送信したハッシュと一致する必要がある;
  • timestampMillisは最新でなければなりません — 鮮度ウィンドウ(許容されるミリ秒の範囲)と比較し、古いものは拒否してください。古いトークンはリプレイの候補になるためです。

Google Playはさらに自動リプレイ保護を適用し、整合性トークンが何度も再利用されるのを防ぎます。これはセーフティネットとして捉え、自前の鮮度チェックの代わりにはしないでください。また、トークンを1日キャッシュするのではなく、アクションの瞬間にサーバー側でデコードしましょう。

6. 過剰ブロックせずにペイロードを読み取る

ペイロードはrequestDetails、appIntegrity、deviceIntegrity、accountDetails、そしてオプトイン後はenvironmentDetailsを含むJSONです。フィールドの順序は保証されないため、常にキーで読み取ってください。実用的な判断の手順は次のとおりです。

  1. まずアプリを確認します:PLAY_RECOGNIZEDは、バイナリと証明書がPlayの配信するものであることを意味します。
  2. 次にデバイスに目を向けましょう。MEETS_DEVICE_INTEGRITYがデフォルトの基準です。追加のラベル — MEETS_BASIC_INTEGRITY、MEETS_STRONG_INTEGRITY、MEETS_VIRTUAL_INTEGRITY — はオプトインであり、段階的な戦略に属するもので、初回リリース向けではありません。
  3. 権限が重要になる場面ではaccountDetailsを使用してください。UNLICENSEDはアカウントにPlayの権限がないことを意味しますが、古い端末ではアンインストール後も権限が残ることがあるため、事実ではなくシグナルとして扱ってください。
  4. environmentDetailsを有効にしている場合、appAccessRiskVerdictは、画面キャプチャやオーバーレイ描画が可能なアプリが存在するかどうかを示します。そのappsDetectedリストにはKNOWN_INSTALLED、UNKNOWN_INSTALLED、UNKNOWN_CAPTURINGなどの値が使われ、Play Protectの判定はデバイスのPlay Protect状態を要約します。

見落とされがちな2つのケースに設計上の注意が必要です。システム整合性チェックを通過し、Androidの主要な互換性要件を満たすエミュレーターは、独自のデバイスラベルを受け取る可能性があるため、「エミュレーター」が自動的に「攻撃者」を意味するわけではありません。また、どのラベルにも該当しないデバイスはこのフィールドを完全に省略するため、キーが常に存在すると仮定したコードはフェイルクローズではなくクラッシュします。

7. クォータ、エラーコード、安全な失敗のさせ方

デフォルトでは、アプリはすべてのインストールを合わせて1日あたり最大10,000リクエストを送信できます。この上限はローンチ後にチームの予想より早く訪れるため、リンクされたCloudプロジェクトで使用状況を監視し、トレンドに余裕があるうちに上限引き上げを申請してください。超過するとTOO_MANY_REQUESTS(エラーコード-8)として現れるので、ユーザーをブロックするのではなく指数バックオフで吸収します。

連携でつまずくのは、たいていエラー処理です。次のエラーは一時的なものとして扱い、バックオフを伴うリトライを行ってください:NETWORK_ERROR(-3)、TOO_MANY_REQUESTS(-8)、GOOGLE_SERVER_UNAVAILABLE(-12)、CLIENT_TRANSIENT_ERROR(-18)。それ以外は環境要因です。Playストアがない、Play servicesがない、Play servicesのバージョンが古い、Playアカウントがない、APIが拒否するCloudプロジェクト番号などが該当します。これらについてGoogleが示す指針は、クライアントがチェックに失敗した場合と同じ結果として扱うことです。ただし、合理的に可能な範囲で操作は引き続き使えるようにしてください。

エラーは単なるコードパスではなく、ポリシーの問題として扱ってください。端末が不審に見える全員をブロックすると、不正対策のシグナルが継続率の問題に変わってしまいます。すべての失敗を黙って無視するのは逆の誤りです。画面ごとに判断しましょう。リーダーボードは寛容に、ウォレットへのチャージは厳格に。そして判断を書き残し、次のエンジニアがその理由を引き継げるようにしてください。

Googleは是正ダイアログも提供しています。これはアプリが起動する、Googleが導くフローで、正規のユーザーがPlayから公式ビルドをインストールしたり接続を復元したりして根本的な問題を修復できるようにするもので、行き止まりに置き去りにしません。また、執行後に同じハードウェアからの繰り返しの不正利用を見つける必要がある場合は、デバイスリコール機能(ベータ)がそのために作られています。

8. ユーザーを壊さずに展開する

執行前のテレメトリー。何かをゲートする前に、判定結果とその分布を数週間ログに記録し、他人のブログ記事ではなく自社のインストールベースにおけるUNEVALUATEDとUNLICENSEDの実際の割合を把握しましょう。その後は段階的に執行します。まずデフォルトのデバイスラベル、次に追加ラベル、そして一度に1つの画面ずつです。クライアントが「再試行」と「不可」を区別できるようにし、APIが単に利用できない場合にアプリが優雅に縮退することを確認してください。不安定なネットワークのユーザーが、すでに支払ったコンテンツへのアクセスを失うべきではありません。

9. KappSの位置づけ

KappSは、デベロッパーがアカウントとリリースをプラットフォームの審査に耐える状態に保つのを支援する — 準拠した素材を準備して提出するのであって、チェックを回避するのではない。具体的には:

  • リリースの衛生管理。 Play App Signingで署名され、公式チャネル経由でアップロードされ、バージョンコードと証明書がGoogle Playが認識する記録と一致していること — これがPLAY_RECOGNIZEDがそもそも成立する条件です。
  • アカウントの準備状況。デベロッパー本人確認、支払いプロフィール、税務記録をアカウントの背後にある法的身元と一致させ、無関係な審査でローンチが滞らないようにします。
  • 統合レビュー。 クライアントがトークンをどのようにリクエストするか、サーバーが何で分岐するか、執行層がビジネスリスクと一致しているかに、もう一組の目を向けます。

当社は、整合性バイパス、判定の偽装、改ざんされたビルドをPlayから隠すツールを提供しておらず、今後も提供しません。これらはまさにこのAPIが検出するために存在するものであり、アカウントを危険にさらし、当社が提供するサービスではありません。整合性チェックに合格する唯一の持続的な方法は、本物であることです。

出典(Google公式ドキュメント):Play Integrity API——概要、セットアップ、標準リクエストの送信、クラシックリクエストの送信、整合性判定について、デバイスリコールの使用、エラーコードの処理、リメディエーションダイアログ(developer.android.com)。

デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。

クリックしてファイルを選択 · 右クリック→貼り付け、またはCtrl/⌘+Vでスクリーンショットを貼り付け

このボックスにファイルをドラッグすることもできます。

ご提供いただいたメールに返信します。お客様の情報はKappS内に留まります。

✔ 送信済み

メッセージを受け付けました。24時間以内に返信します。


← 編集に戻る