修正ダイアログ

このページでは、完全性判定の結果に関する問題への対処方法について説明します。

完全性トークンがリクエストされたときに、ユーザーに Google Play ダイアログを表示できます。完全性判定の結果に 1 つ以上の問題がある場合や、Integrity API リクエスト中に例外が発生した場合は、ダイアログを閉じると、別の完全性トークン リクエストで問題が修正されたことを確認できます。標準リクエストを実行する場合は、トークン プロバイダを再度ウォームアップして、新しい判定結果を取得する必要があります。

完全性ダイアログをリクエストして判定の問題を修正する

クライアントが完全性トークンをリクエストすると、StandardIntegrityToken（標準 API）と IntegrityTokenResponse（クラシック API）で提供されているメソッド showDialog(Activity activity, int integrityDialogTypeCode) を使用できます。

Play Integrity API を使用して GET_LICENSED ダイアログ コードで修正ダイアログを表示する手順は次のとおりです。アプリがリクエストできるその他のダイアログ コードについては、このセクションの後に記載されています。

  1. アプリから完全性トークンをリクエストし、そのトークンをサーバーに送信します。標準リクエストまたはクラシック リクエストを使用できます。

    Kotlin

    // Request an integrity token
val tokenResponse: StandardIntegrityToken = requestIntegrityToken()
// Send token to app server and get response on what to do next
val yourServerResponse: YourServerResponse = sendToServer(tokenResponse.token())

    Java

    // Request an integrity token
StandardIntegrityToken tokenResponse = requestIntegrityToken();
// Send token to app server and get response on what to do next
YourServerResponse yourServerResponse = sendToServer(tokenResponse.token());

    Unity

    // Request an integrity token
StandardIntegrityToken tokenResponse = RequestIntegrityToken();
// Send token to app server and get response on what to do next
YourServerResponse yourServerResponse = sendToServer(tokenResponse.Token);

    Unreal Engine

    // Request an integrity token
StandardIntegrityToken* Response = RequestIntegrityToken();
// Send token to app server and get response on what to do next
YourServerResponse YourServerResponse = SendToServer(Response->Token);

    ネイティブ

    /// Request an integrity token
StandardIntegrityToken* response = requestIntegrityToken();
/// Send token to app server and get response on what to do next
YourServerResponse yourServerResponse = sendToServer(StandardIntegrityToken_getToken(response));

  2. サーバーで、完全性トークンを復号し、appLicensingVerdict フィールドを確認します。次のようになります。

    // Licensing issue
{
    ...
    "accountDetails": {
        "appLicensingVerdict": "UNLICENSED"
    }
}

  3. トークンに appLicensingVerdict: "UNLICENSED" が含まれている場合は、アプリ クライアントに返信し、ライセンス ダイアログを表示するようリクエストします。

    Kotlin

    private fun getDialogTypeCode(integrityToken: String): Int{
    // Get licensing verdict from decrypted and verified integritytoken
    val licensingVerdict: String = getLicensingVerdictFromDecryptedToken(integrityToken)

    return if (licensingVerdict == "UNLICENSED") {
            1 // GET_LICENSED
        } else 0
}

    Java

    private int getDialogTypeCode(String integrityToken) {
    // Get licensing verdict from decrypted and verified integrityToken
    String licensingVerdict = getLicensingVerdictFromDecryptedToken(integrityToken);

    if (licensingVerdict.equals("UNLICENSED")) {
      return 1; // GET_LICENSED
    }
    return 0;
}

    Unity

    private int GetDialogTypeCode(string IntegrityToken) {
    // Get licensing verdict from decrypted and verified integrityToken
    string licensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken);

    if (licensingVerdict == "UNLICENSED") {
      return 1; // GET_LICENSED
    }
    return 0;
}

    Unreal Engine

    private int GetDialogTypeCode(FString IntegrityToken) {
    // Get licensing verdict from decrypted and verified integrityToken
    FString LicensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken);

    if (LicensingVerdict == "UNLICENSED") {
      return 1; // GET_LICENSED
    }
    return 0;
}

    ネイティブ

    private int getDialogTypeCode(string integrity_token) {
    /// Get licensing verdict from decrypted and verified integrityToken
    string licensing_verdict = getLicensingVerdictFromDecryptedToken(integrity_token);

    if (licensing_verdict == "UNLICENSED") {
      return 1; // GET_LICENSED
    }
    return 0;
}

  4. アプリで、サーバーから取得したコードを使用して、showDialog を呼び出します。

    Kotlin

    // Show dialog as indicated by the server
val showDialogType: Int? = yourServerResponse.integrityDialogTypeCode()
if (showDialogType == null) {
     return
}

// Create dialog request
val dialogRequest = StandardIntegrityDialogRequest.builder()
          .setActivity(activity)
          .setTypeCode(showDialogType)
          .setStandardIntegrityResponse(StandardIntegrityResponse.TokenResponse(token))
          .build()

// Call showDialog, the dialog will be shown on top of the provided activity
// and the task will complete when the dialog is closed.
val result: Task<Int> = standardIntegrityManager.showDialog(dialogRequest)

// Handle response code, call the Integrity API again to confirm that the
// verdict issue has been resolved.

    Java

    // Show dialog as indicated by the server
@Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode();
if (showDialogType == null) {
     return;
}

// Create dialog request
StandardIntegrityDialogRequest dialogRequest =
      StandardIntegrityDialogRequest.builder()
          .setActivity(getActivity())
          .setTypeCode(showDialogTypeCode)
          .setStandardIntegrityResponse(new StandardIntegrityResponse.TokenResponse(token))
          .build();

// Call showDialog, the dialog will be shown on top of the provided activity
// and the task will complete when the dialog is closed.
Task<Integer> result = standardIntegrityManager.showDialog(dialogRequest);

// Handle response code, call the Integrity API again to confirm that the
// verdict issue has been resolved.

    Unity

    // Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or
// higher.
var standardIntegrityManager = new StandardIntegrityManagerV2();
IEnumerator ShowDialogCoroutine() {
    int showDialogType = yourServerResponse.IntegrityDialogTypeCode();

    PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask;

    using (var activity = UnityPlayerHelper.GetCurrentActivity())
    {
        // Create a dialog request
        var dialogRequest = new StandardIntegrityDialogRequest(tokenResponse, activity, showDialogType);

        // Call showDialog with the request, the dialog will be shown on top of the
        // provided activity and complete when the dialog is closed.
        showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest);
    }

    // Wait for PlayAsyncOperation to complete.
    yield return showDialogTask;

    // Handle response code, call the Integrity API again to confirm that the
    // verdict issue been resolved.
}

    Unreal Engine

    // .h
void MyClass::OnShowDialogCompleted(
    EStandardIntegrityErrorCode Error,
    EIntegrityDialogResponseCode Response)
{
    // Handle response code, call the Integrity API again to confirm that the
    // verdict issue has been resolved.
}

// .cpp
void MyClass::RequestIntegrityToken()
{
    UStandardIntegrityToken* Response = ...
    int TypeCode = YourServerResponse.integrityDialogTypeCode();

    // Create a delegate to bind the callback function.
    FShowDialogStandardOperationCompletedDelegate Delegate;

    // Bind the completion handler (OnShowDialogCompleted) to the delegate.
    Delegate.BindDynamic(this, &MyClass::OnShowDialogCompleted);

    // Call ShowDialog with TypeCode which completes when the dialog is closed.
    Response->ShowDialog(TypeCode, Delegate);
}

    ネイティブ

    // Show dialog as indicated by the server
int show_dialog_type = yourServerResponse.integrityDialogTypeCode();
if(show_dialog_type == 0){
  return;
}

/// Create dialog request
StandardIntegrityDialogRequest* dialog_request;
StandardIntegrityDialogRequest_create(&dialog_request);
StandardIntegrityDialogRequest_setTypeCode(dialog_request, show_dialog_type);
StandardIntegrityDialogRequest_setActivity(dialog_request, activity);
StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request,
                                                token_response);

/// Call showDialog with the dialog request. The dialog will be shown on top
/// of the provided activity and complete when the dialog is closed by the
/// user.
StandardIntegrityDialogResponse* dialog_response;
StandardIntegrityErrorCode error_code =
    StandardIntegrityManager_showDialog(dialog_request, &dialog_response);

/// Use polling to wait for the async operation to complete. Note, the polling
/// shouldn't block the thread where the StandardIntegrityManager is running.
IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN;
while (error_code == STANDARD_INTEGRITY_NO_ERROR) {
    error_code = StandardIntegrityDialogResponse_getResponseCode(dialog_response, &response_code);
    if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){
      break;
    }
}

/// Free memory
StandardIntegrityDialogRequest_destroy(dialog_request);
StandardIntegrityDialogResponse_destroy(dialog_response);

/// Handle response code, call the Integrity API again to confirm that the
/// verdict issues have been resolved.

  5. ダイアログは提供されたアクティビティの上に表示されます。ユーザーがダイアログを閉じると、タスクはレスポンス コードを返して完了します。

  6. （省略可）さらにダイアログを表示するには、別のトークンをリクエストします。標準リクエストを実行する場合は、トークン プロバイダを再度ウォームアップして、新しい判定結果を取得する必要があります。

クライアントサイドの例外を修正するために完全性ダイアログをリクエストする

Integrity API リクエストが StandardIntegrityException（Standard API）または IntegrityServiceException（Classic API）で失敗し、例外が修正可能な場合は、GET_INTEGRITY または GET_STRONG_INTEGRITY ダイアログを使用してエラーを修正できます。

GET_INTEGRITY ダイアログを使用して、Integrity API によって報告された修正可能なクライアントサイド エラーを修正する手順は次のとおりです。

  1. Integrity API リクエストから返された例外が修正可能かどうかを確認します。

    Kotlin

    private fun isExceptionRemediable(exception: ExecutionException): Boolean {
    val cause = exception.cause
    if (cause is StandardIntegrityException && cause.isRemediable) {
        return true
    }
    return false
}

    Java

    private boolean isExceptionRemediable(ExecutionException exception) {
    Throwable cause = exception.getCause();
    if (cause instanceof StandardIntegrityException integrityException
&& integrityException.isRemediable()) {
        return true;
    }
    return false;
}

    Unity

    private bool IsExceptionRemediable(StandardIntegrityError error) {
    // Check if the operation resulted in a remediable error
    if (error != null && error.ErrorCode != StandardIntegrityErrorCode.NoError && error.IsRemediable) {
        return true;
    }
    return false;
}

    ネイティブ

    bool IsErrorRemediable(StandardIntegrityToken* token) {
    /// Check if the error associated with the token is remediable
    bool isRemediable = false;
    if(StandardIntegrityToken_getIsRemediable(response, &isRemediable) == STANDARD_INTEGRITY_NO_ERROR){
      return isRemediable;
    }
    return false;
}

  2. 例外が修正可能な場合は、返された例外を使用して GET_INTEGRITY ダイアログをリクエストします。ダイアログは指定されたアクティビティの上に表示され、ユーザーがダイアログを閉じると、返されたタスクはレスポンス コードを返して完了します。

    Kotlin

      private fun showDialog(exception: StandardIntegrityException) {
      // Create a dialog request
      val standardIntegrityDialogRequest =
          StandardIntegrityDialogRequest.builder()
              .setActivity(activity)
              .setType(IntegrityDialogTypeCode.GET_INTEGRITY)
              .setStandardIntegrityResponse(ExceptionDetails(exception))
              .build()

      // Request dialog
      val responseCode: Task<Int> =
            standardIntegrityManager.showDialog(standardIntegrityDialogRequest)
}

    Java

      private void showDialog(StandardIntegrityException exception) {
      // Create a dialog request
      StandardIntegrityDialogRequest standardIntegrityDialogRequest =
          StandardIntegrityDialogRequest.builder()
              .setActivity(this.activity)
              .setType(IntegrityDialogTypeCode.GET_INTEGRITY)
              .setStandardIntegrityResponse(new ExceptionDetails(exception))
              .build();

      // Request dialog
      Task<Integer> responseCode =
            standardIntegrityManager.showDialog(standardIntegrityDialogRequest);
}

    Unity

    // Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or
// higher.
var standardIntegrityManager = new StandardIntegrityManagerV2();
IEnumerator ShowDialogToFixError(StandardIntegrityError error) {
    PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask;

    using (var activity = UnityPlayerHelper.GetCurrentActivity())
    {
        // Create a dialog request using the error
        var dialogRequest = new StandardIntegrityDialogRequest(error, activity, GET_INTEGRITY_DIALOG);

        // Request dialog
        showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest);
    }

    // Wait for PlayAsyncOperation to complete.
    yield return showDialogTask;
}

    ネイティブ

    private void showDialogToFixError(StandardIntegrityToken* token) {
    /// If the token request failed, and the underlying error is not fixable
    /// then return early
    if(isErrorRemediable(token)) {
      return;
    }

    /// Create dialog request
    StandardIntegrityDialogRequest* dialog_request;
    StandardIntegrityDialogRequest_create(&dialog_request);
    StandardIntegrityDialogRequest_setTypeCode(dialog_request,
                                       kGetIntegrityDialogTypeCode);
    StandardIntegrityDialogRequest_setActivity(dialog_request, activity);
    StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request,
                                                    token_response);

    /// Call showDialog with the dialog request. The dialog will be shown on
    /// top of the provided activity and complete when the dialog is closed by
    /// the user.
    StandardIntegrityDialogResponse* dialog_response;
    StandardIntegrityErrorCode error_code =
        StandardIntegrityManager_showDialog(dialog_request, &dialog_response);

    /// Use polling to wait for the async operation to complete.
    /// Note, the polling shouldn't block the thread where the
    /// StandardIntegrityManager is running.
    IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN;
    while (error_code == STANDARD_INTEGRITY_NO_ERROR) {
        error_code = StandardIntegrityDialogResponse_getResponseCode(response, &response_code);
        if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){
          break;
        }
    }

    /// Free memory
    StandardIntegrityDialogRequest_destroy(dialog_request);
    StandardIntegrityDialogResponse_destroy(dialog_response);

}

  3. 返されたレスポンス コードが成功を示している場合、次の完全性トークンのリクエストは例外なく成功するはずです。標準リクエストを実行する場合は、トークン プロバイダを再度ウォームアップして、新しい判定結果を取得する必要があります。

完全性ダイアログ コード

GET_LICENSED（タイプコード 1）

判定に関する問題

このダイアログは、次の 2 つの問題に適しています。

  • 不正アクセス: appLicensingVerdict: "UNLICENSED"。これは、ユーザー アカウントにアプリの利用資格がないことを意味します。これは、ユーザーがアプリをサイドローディングした場合や、Google Play 以外のアプリストアから取得した場合に発生する可能性があります。
  • 改ざんされたアプリ: appRecognitionVerdict: "UNRECOGNIZED_VERSION"。これは、アプリのバイナリが変更されているか、Google Play で認識されているバージョンではないことを意味します。

修復

GET_LICENSED ダイアログを表示して、Google Play から正規のアプリを入手するようユーザーに促すことができます。この 1 つのダイアログで、次の両方のシナリオに対応します。

  • ライセンスのないユーザーの場合は、Google Play ライセンスが付与されます。これにより、ユーザーは Google Play からアプリ アップデートを受け取ることができます。
  • 改ざんされたアプリ バージョンを使用しているユーザーに対しては、変更されていないアプリを Google Play からインストールするよう案内します。

ユーザーがダイアログを完了すると、後続の整合性チェックで appLicensingVerdict: "LICENSED" と appRecognitionVerdict: "PLAY_RECOGNIZED" が返されます。

UX の例

図 1. Google Play の GET_LICENSED ダイアログ。

CLOSE_UNKNOWN_ACCESS_RISK（タイプコード 2）

判定に関する問題

environmentDetails.appAccessRiskVerdict.appsDetected に "UNKNOWN_CAPTURING" または "UNKNOWN_CONTROLLING" が含まれている場合、画面のキャプチャやデバイスの制御を行う可能性のある他のアプリ（Google Play によってインストールされたアプリ、またはデバイスのメーカーによってシステム パーティションにプリロードされたアプリではないアプリ）がデバイス上で実行されていることを意味します。

修復

CLOSE_UNKNOWN_ACCESS_RISK ダイアログを表示して、画面をキャプチャしたりデバイスを制御したりしている可能性のある不明なアプリをすべて閉じるようユーザーに求めることができます。ユーザーが Close all ボタンをタップすると、そのようなアプリはすべて閉じられます。

UX の例

図 2. 不明なアクセスリスクを閉じるためのダイアログ。

CLOSE_ALL_ACCESS_RISK（タイプコード 3）

判定に関する問題

environmentDetails.appAccessRiskVerdict.appsDetected に "KNOWN_CAPTURING"、"KNOWN_CONTROLLING"、"UNKNOWN_CAPTURING"、"UNKNOWN_CONTROLLING" のいずれかが含まれている場合、画面をキャプチャしたりデバイスを操作したりする可能性のあるアプリがデバイス上で実行されていることを意味します。

修復

CLOSE_ALL_ACCESS_RISK ダイアログを表示して、画面のキャプチャやデバイスの操作を行っている可能性のあるすべてのアプリを閉じるようユーザーに促すことができます。ユーザーが Close all ボタンをタップすると、そのようなアプリはすべてデバイス上で終了します。

UX の例

図 3. すべてのアクセスリスクを閉じるためのダイアログ。

GET_INTEGRITY（タイプコード 4）

判定に関する問題

このダイアログは、次のいずれかの問題に適しています。

  • 弱いデバイスの完全性: deviceRecognitionVerdict に MEETS_DEVICE_INTEGRITY が含まれていない場合、デバイスは正規の認定 Android 搭載デバイスではない可能性があります。たとえば、デバイスのブートローダーがロック解除されている場合や、読み込まれた Android OS が認定メーカーのイメージでない場合などです。

  • 不正アクセス: appLicensingVerdict: "UNLICENSED"。これは、ユーザー アカウントにアプリの利用資格がないことを意味します。これは、ユーザーがアプリをサイドローディングした場合や、Google Play 以外のアプリストアから取得した場合に発生する可能性があります。

  • 改ざんされたアプリ: appRecognitionVerdict: "UNRECOGNIZED_VERSION"。これは、アプリのバイナリが変更されているか、Google Play で認識されているバージョンではないことを意味します。

  • クライアントサイドの例外: Integrity API リクエスト中に修正可能な例外が発生した場合。修正可能な例外は、PLAY_SERVICES_VERSION_OUTDATED、NETWORK_ERROR、PLAY_SERVICES_NOT_FOUND などのエラーコードを含む Integrity API の例外です。exception.isRemediable() メソッドを使用すると、例外がダイアログで修正可能かどうかを確認できます。

修復

GET_INTEGRITY ダイアログは、1 つの継続的なフロー内で複数の修復手順を処理することで、ユーザー エクスペリエンスを効率化するように設計されています。これにより、ユーザーは複数の異なるダイアログを操作してさまざまな問題を修正する必要がなくなります。

ダイアログをリクエストすると、対象となる判定の問題が自動的に検出され、適切な修正手順が提供されます。つまり、1 つのダイアログ リクエストで、次のような複数の問題に一度に対処できます。

  • デバイスの完全性: デバイスの完全性に関する問題が検出された場合、ダイアログは、MEETS_DEVICE_INTEGRITY 判定の要件を満たすようにデバイスのセキュリティ ステータスを改善するようユーザーに指示します。
  • アプリの完全性: 不正アクセスやアプリの改ざんなどの問題が検出された場合、ダイアログはユーザーに Google Play ストアからアプリを取得して問題を解決するよう指示します。
  • クライアントサイドの例外: ダイアログは、Integrity API の例外の原因となった根本的な問題を確認し、解決を試みます。たとえば、古いバージョンの Google Play 開発者サービスを更新するようユーザーに求めることができます。

UX の例

図 4. GET_INTEGRITY ダイアログのネットワーク エラーの修復フロー

GET_STRONG_INTEGRITY（タイプコード 5）

判定に関する問題

このダイアログは、GET_INTEGRITY が対処するすべての問題に加えて、デバイスが MEETS_STRONG_INTEGRITY 判定を受信できない問題や、Play プロテクトの判定に関する問題を修正するように設計されています。

修復

GET_STRONG_INTEGRITY は、1 つの継続的なフロー内で複数の修復手順を処理することで、ユーザー エクスペリエンスを効率化するように設計されています。このダイアログでは、次のようなアドレスに該当する整合性の問題が自動的にチェックされます。

  • デバイスの完全性: デバイスの完全性に関する問題が検出された場合、ダイアログは、MEETS_STRONG_INTEGRITY 判定の要件を満たすようにデバイスのセキュリティ ステータスを改善するようユーザーに指示します。

  • Play プロテクトのステータス: playProtectVerdict が問題を示している場合、ダイアログはユーザーに修正を案内します。

    • Play プロテクトが無効になっている場合（playProtectVerdict == POSSIBLE_RISK）、ダイアログが表示され、Play プロテクトを有効にしてデバイス上のすべてのアプリをスキャンするようにユーザーに促します。
    • 有害なアプリ（playProtectVerdict == MEDIUM_RISK または HIGH_RISK）が検出された場合、ダイアログは Google Play プロテクトを使用してアンインストールするようユーザーに指示します。

  • アプリの完全性: 不正アクセスやアプリの改ざんなどの問題が検出された場合、ダイアログはユーザーに Google Play ストアからアプリを取得して問題を解決するよう促します。

  • クライアントサイドの例外: ダイアログは、Integrity API の例外の原因となった根本的な問題の解決も試みます。たとえば、Google Play 開発者サービスが無効になっていることが判明した場合は、有効にするようユーザーに求めることができます。修復可能な例外は、PLAY_SERVICES_VERSION_OUTDATED、NETWORK_ERROR、PLAY_SERVICES_NOT_FOUND などのエラーコードを含む Integrity API の例外です。exception.isRemediable() メソッドを使用すると、ダイアログでエラーを修正できるかどうかを確認できます。

UX の例

図 5. Google Play 開発者サービスを更新する GET_STRONG_INTEGRITY ダイアログ。
前へ
エラーコードを処理する
次へ
その他のツールとサポート