SafetyNet Attestation API からの移行

すでに信頼できるサーバーを使用してレスポンスを検証している場合、SafetyNet Attestation API から Play Integrity API への移行は簡単です。Play Integrity API は、AIDL を介して Play ストア アプリで直接実行されるアプリのライセンスのチェック(例: License Verification Librar(LVL)によって実行されるライセンス チェック)の代替手段としても使用できます。必要な変更のほとんどは信頼できるサーバーサイドで行われるため、必要なとなるのは Play の整合性レスポンス トークンの読み取りと分析だけです。まだ更新していない古いクライアントをサポートするには、移行中にアプリケーションとサーバーの両方で両方の API を同時にサポートする必要があることに留意してください。

SafetyNet Attestation API の割り当て上限が引き上げられたアプリの場合は、割り当てられている Play Integrity API の使用量ティアを確認し、必要に応じてティアの引き上げをリクエストしてください。

Play Integrity API をサポートするには、次の変更が必要です。

Android クライアント:

  • コードが正しい形式のノンスを IntegrityTokenRequest ビルダーに渡すようにします。
    • String(バイト配列ではなく)
    • URL-safe
    • Base64、ラップなしでエンコード
    • 16 文字以上
    • 最大 500 文字
  • 再試行ロジックを確認し、アプリケーションがエラーを適切に処理できる状態にします。
  • 信頼できるサーバーに送信されるレスポンス データで、SafetyNet Attestation API レスポンスと Play Integrity API レスポンスを区別できるようにしてください。

信頼できるサーバー:

  • ノンスの生成ロジックを確認し、Play Integrity API の要件を満たすようにします。
  • サーバーコードで SafetyNet Attestation API レスポンスと Play Integrity API レスポンスを区別できるようにします。コードでこれらのレスポンスが適切に解析および検証されるようにします。
  • Play Integrity API レスポンスの検証と解析を行うロジックを追加します。
  • 新しい Play Integrity API レスポンスでは詳細な情報が得られるため、意思決定ロジックと、クライアント デバイスに返送されるフィードバック データを強化することが必要な場合があります。詳細については、このトピック内の API レスポンス マッピングのセクションをご覧ください。

ノンス エンコード

整合性関連のノンスは、Base64 ベース エンコード、URL セーフ、かつラップなし String として Play Integrity API に渡す必要があります。この形式は、byte[] を必要とする SafetyNet Attestation API とは異なります。

  • 「URL セーフ」とは、Base64 の「URL セーフおよびファイル名セーフ型」のバリアントを使用することを表します(RFC 4648 のセクション 5 を参照)。「URL セーフ」では「+」と「/」の代わりに「-」と「_」が使用されます。Base64 エンコードの詳細については、RFC 4648 をご覧ください。
  • 「ラップなし」は、すべての行末を省略することを表します。つまり、出力は 1 行になります。
.setNonce(Base64.encodeToString(NONCE_BYTES,
        Base64.URL_SAFE | Base64.NO_WRAP))

また、ノンスの生成が Play Integrity API ガイドラインに沿って行われるようにしてください。

API レスポンスのマッピング

次の表では、SafetyNet Attestation API のフィールドを Play Integrity API の対応するフィールドにマッピングしています。

SafetyNet Attestation API Play Integrity API
timestampMs requestDetails.timestampMillis
nonce requestDetails.nonce
apkPackageName appIntegrity.packageName
apkCertificateDigestSha256 appIntegrity.certificateSha256Digest appRecognitionVerdictPLAY_RECOGNIZED に設定されるようにします。
ctsProfileMatch deviceIntegrity.deviceRecognitionVerdict への統合
basicIntegrity deviceIntegrity.deviceRecognitionVerdict への統合
evaluationType deviceIntegrity.deviceRecognitionVerdict への統合
advice Not available
error Not available デバイスの完全性ラベルのリストは空になります。

デバイスの完全性判定の結果のマッピング

SafetyNet Attestation API Play Integrity API
ctsProfileMatch basicIntegrity evaluationType deviceRecognitionVerdict
FALSE FALSE ラベルなし
FALSE TRUE MEETS_BASIC_INTEGRITY
TRUE FALSE ラベルなし
TRUE TRUE BASIC MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
TRUE TRUE HARDWARE_BACKED MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY

アプリが複雑な適用戦略を使用しており、設定可能なすべての値を必要とする場合は、デバイスの整合性レスポンスのセットを設定することが必要な場合があります。

Play Integrity API の再試行ロジック

特定のエラーコードが発生した場合、アプリは API 呼び出しを再試行する必要があります。すべてのエラーコードを確認し、アプリケーションが必要に応じて指数バックオフで再試行するようにします。最小遅延を 5 秒以上とし、指数関数的に増加させて(5 秒、10 秒、20 秒、40 秒など)、デバイスとアプリの整合性を API が評価するのに十分な時間を確保してください。

App Licensing API の代替オプション

App Licensing API を使用している場合は、Play Integrity API トークンにアプリのライセンス情報が含まれるため、必要に応じて Play Integrity API を使用するように移行できます。SafetyNet Attestation API の移行と同様、デバイスの旧バージョンが多数のデバイスに保持されることを想定する必要があります。信頼できるサーバーは、App Licensing API と Play Integrity API の両方のレスポンスを処理できる必要があります。