Halaman ini diterjemahkan oleh Cloud Translation API.

Dialog perbaikan

Halaman ini menjelaskan cara menangani masalah terkait verdict integritas.

Setelah token integritas diminta, Anda memiliki opsi untuk menampilkan dialog Google Play kepada pengguna. Anda dapat menampilkan dialog jika ada satu atau beberapa masalah dengan verdict integritas atau jika terjadi pengecualian selama permintaan Integrity API. Setelah dialog ditutup, Anda dapat memverifikasi bahwa masalah telah diperbaiki dengan mengirim permintaan token integritas lain. Jika membuat permintaan standar, Anda harus melakukan persiapan ulang penyedia token untuk mendapatkan verdict baru.

Meminta dialog integritas untuk memperbaiki masalah verdict

Saat klien meminta token integritas, Anda dapat menggunakan metode yang ditawarkan dalam StandardIntegrityToken (Standard API) dan IntegrityTokenResponse (Classic API): showDialog(Activity activity, int integrityDialogTypeCode).

Langkah-langkah berikut menguraikan cara menggunakan Play Integrity API untuk menampilkan dialog perbaikan menggunakan kode dialog GET_LICENSED. Kode dialog lain yang dapat diminta oleh aplikasi Anda tercantum setelah bagian ini.

Minta token integritas dari aplikasi Anda, lalu kirim token tersebut ke server Anda. Anda dapat menggunakan permintaan Standar atau Klasik.

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);

Native

/// 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));

Di server, dekripsi token integritas dan periksa kolom appLicensingVerdict. Token akan tampak seperti berikut:

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

Jika token berisi appLicensingVerdict: "UNLICENSED", balas klien aplikasi Anda dengan memintanya menampilkan dialog pemberian lisensi:

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;
}

Native

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;
}

Di aplikasi Anda, panggil showDialog dengan kode yang diminta yang diambil dari server Anda:

Kotlin

// Show dialog as indicated by the server
val showDialogType: Int? = yourServerResponse.integrityDialogTypeCode()
if (showDialogType != null) {
  // Call showDialog with type code, the dialog will be shown on top of the
  // provided activity and complete when the dialog is closed.
  val integrityDialogResponseCode: Task<Int> =
  tokenResponse.showDialog(activity, showDialogType)
  // Handle response code, call the Integrity API again to confirm that
  // verdicts have been resolved.
}

Java

// Show dialog as indicated by the server
@Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode();
if (showDialogType != null) {
  // Call showDialog with type code, the dialog will be shown on top of the
  // provided activity and complete when the dialog is closed.
  Task<Integer> integrityDialogResponseCode =
      tokenResponse.showDialog(activity, showDialogType);
  // Handle response code, call the Integrity API again to confirm that
  // verdicts have been resolved.
}

Unity

IEnumerator ShowDialogCoroutine() {
  int showDialogType = yourServerResponse.IntegrityDialogTypeCode();

  // Call showDialog with type code, the dialog will be shown on top of the
  // provided activity and complete when the dialog is closed.
  var showDialogTask = tokenResponse.ShowDialog(showDialogType);

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

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

Unreal Engine

// .h
void MyClass::OnShowDialogCompleted(
  EStandardIntegrityErrorCode Error,
  EIntegrityDialogResponseCode Response)
{
  // Handle response code, call the Integrity API again to confirm that
  // verdicts have 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);
}

Native

// Show dialog as indicated by the server
int show_dialog_type = yourServerResponse.integrityDialogTypeCode();
if (show_dialog_type != 0) {
  /// Call showDialog with type code, the dialog will be shown on top of the
  /// provided activity and complete when the dialog is closed.
  StandardIntegrityErrorCode error_code =
      IntegrityTokenResponse_showDialog(response, activity, show_dialog_type);

  /// Proceed to polling iff error_code == STANDARD_INTEGRITY_NO_ERROR
  if (error_code != STANDARD_INTEGRITY_NO_ERROR)
  {
      /// Remember to call the *_destroy() functions.
      return;
  }

  /// Use polling to wait for the async operation to complete.
  /// Note, the polling shouldn't block the thread where the IntegrityManager
  /// is running.

  IntegrityDialogResponseCode* response_code;
  error_code = StandardIntegrityToken_getDialogResponseCode(response, response_code);

  if (error_code != STANDARD_INTEGRITY_NO_ERROR)
  {
      /// Remember to call the *_destroy() functions.
      return;
  }

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

Dialog ditampilkan di atas aktivitas yang disediakan. Saat pengguna menutup dialog, Tugas akan selesai dengan kode respons.
(Opsional) Minta token lain untuk menampilkan dialog lebih lanjut. Jika membuat permintaan standar, Anda harus melakukan persiapan ulang penyedia token untuk mendapatkan verdict baru.

Meminta dialog integritas untuk memperbaiki pengecualian sisi klien

Jika permintaan Integrity API gagal dengan StandardIntegrityException (Standard API) atau IntegrityServiceException (Classic API) dan pengecualian dapat diperbaiki, Anda dapat menggunakan dialog GET_INTEGRITY atau GET_STRONG_INTEGRITY untuk memperbaiki error.

Langkah-langkah berikut menguraikan cara menggunakan dialog GET_INTEGRITY untuk memperbaiki error sisi klien yang dapat diperbaiki yang dilaporkan oleh Integrity API.

Periksa apakah pengecualian yang ditampilkan dari permintaan Integrity API dapat diperbaiki.

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;
}

Jika pengecualian dapat diperbaiki, minta dialog GET_INTEGRITY menggunakan pengecualian yang ditampilkan. Dialog akan ditampilkan di atas aktivitas yang disediakan dan Tugas yang ditampilkan akan selesai dengan kode respons setelah pengguna menutup dialog.

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);
}

Jika kode respons yang ditampilkan menunjukkan keberhasilan, permintaan berikutnya untuk token integritas akan berhasil tanpa pengecualian. Jika membuat permintaan standar, Anda harus melakukan persiapan ulang penyedia token untuk mendapatkan verdict baru.

Kode dialog integritas

GET_LICENSED (Kode Jenis 1)

Masalah verdict

Dialog ini sesuai untuk dua masalah:

Akses tidak sah: appLicensingVerdict: "UNLICENSED". Artinya, akun pengguna tidak memiliki hak atas aplikasi Anda, yang dapat terjadi jika pengguna melakukan sideload atau mendapatkannya dari app store selain Google Play.
Aplikasi yang dimodifikasi: appRecognitionVerdict: "UNRECOGNIZED_VERSION". Hal ini berarti biner aplikasi Anda telah dimodifikasi atau bukan versi yang dikenali oleh Google Play.

Perbaikan

Anda dapat menampilkan dialog GET_LICENSED untuk meminta pengguna mendapatkan aplikasi asli dari Google Play. Satu dialog ini menangani kedua skenario:

Untuk pengguna yang tidak memiliki lisensi, pengguna tersebut akan diberi lisensi Play. Hal ini memungkinkan pengguna menerima update aplikasi dari Google Play.
Untuk pengguna dengan versi aplikasi yang dimodifikasi, pengguna akan dipandu untuk menginstal aplikasi yang tidak dimodifikasi dari Google Play.

Saat pengguna menyelesaikan dialog, pemeriksaan integritas berikutnya akan menampilkan appLicensingVerdict: "LICENSED" dan appRecognitionVerdict: "PLAY_RECOGNIZED".

Contoh UX

CLOSE_UNKNOWN_ACCESS_RISK (Kode Jenis 2)

Masalah verdict

Jika environmentDetails.appAccessRiskVerdict.appsDetected berisi "UNKNOWN_CAPTURING" atau "UNKNOWN_CONTROLLING", berarti ada aplikasi lain (yang tidak diinstal oleh Google Play atau dimuat sebelumnya di partisi sistem oleh produsen perangkat) yang berjalan di perangkat yang dapat merekam layar atau mengontrol perangkat.

Perbaikan

Anda dapat menampilkan dialog CLOSE_UNKNOWN_ACCESS_RISK untuk meminta pengguna menutup semua aplikasi tidak dikenal yang dapat merekam layar atau mengontrol perangkat. Jika pengguna mengetuk tombol Close all, semua aplikasi tersebut akan ditutup.

Contoh UX

**Gambar 2.** Dialog untuk menutup risiko akses tidak dikenal.

CLOSE_ALL_ACCESS_RISK (Kode Jenis 3)

Masalah verdict

Jika environmentDetails.appAccessRiskVerdict.appsDetected berisi salah satu dari "KNOWN_CAPTURING", "KNOWN_CONTROLLING","UNKNOWN_CAPTURING", atau "UNKNOWN_CONTROLLING", berarti ada aplikasi yang berjalan di perangkat yang dapat merekam layar atau mengontrol perangkat.

Perbaikan

Anda dapat menampilkan dialog CLOSE_ALL_ACCESS_RISK untuk meminta pengguna menutup semua aplikasi yang dapat merekam layar atau mengontrol perangkat. Jika pengguna mengetuk tombol Close all, semua aplikasi tersebut akan ditutup di perangkat.

Contoh UX

**Gambar 3.** Dialog untuk menutup semua risiko akses.

GET_INTEGRITY (Kode Jenis 4)

Masalah verdict

Dialog ini sesuai untuk masalah berikut:

Integritas perangkat lemah: Jika deviceRecognitionVerdict tidak berisi MEETS_DEVICE_INTEGRITY, perangkat mungkin bukan perangkat asli yang didukung Android dan bersertifikasi Play Protect. Hal ini dapat terjadi, misalnya jika bootloader perangkat tidak terkunci atau OS Android yang dimuatnya bukan image produsen bersertifikasi.
Akses tidak sah: appLicensingVerdict: "UNLICENSED". Artinya, akun pengguna tidak memiliki hak atas aplikasi Anda, yang dapat terjadi jika pengguna memuat aplikasi dari luar atau memperolehnya dari app store selain Google Play.
Aplikasi yang dimodifikasi: appRecognitionVerdict: "UNRECOGNIZED_VERSION". Artinya, biner aplikasi Anda telah dimodifikasi atau bukan versi yang dikenali oleh Google Play.
Pengecualian sisi klien: Saat pengecualian yang dapat diperbaiki terjadi selama permintaan Integrity API. Pengecualian yang dapat diperbaiki adalah pengecualian Integrity API dengan kode error seperti PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR, PLAY_SERVICES_NOT_FOUND, dll. Anda dapat menggunakan metode exception.isRemediable() untuk memeriksa apakah pengecualian dapat diperbaiki oleh dialog.

Perbaikan

Dialog GET_INTEGRITY dirancang untuk menyederhanakan pengalaman pengguna dengan menangani beberapa langkah perbaikan dalam satu alur berkelanjutan. Hal ini mencegah pengguna harus berinteraksi dengan beberapa dialog terpisah untuk memperbaiki masalah yang berbeda.

Saat Anda meminta dialog, dialog akan otomatis mendeteksi masalah putusan yang ditargetkan dan memberikan langkah-langkah perbaikan yang sesuai. Artinya, satu permintaan dialog dapat mengatasi beberapa masalah sekaligus, termasuk:

Integritas perangkat: Jika masalah integritas perangkat terdeteksi, dialog akan memandu pengguna untuk meningkatkan status keamanan perangkat agar memenuhi persyaratan untuk verdict MEETS_DEVICE_INTEGRITY.
Integritas aplikasi: Jika masalah seperti akses tidak sah atau modifikasi aplikasi terdeteksi, dialog akan mengarahkan pengguna untuk mendapatkan aplikasi dari Play Store guna memperbaikinya.

Pengecualian sisi klien: Dialog memeriksa dan mencoba menyelesaikan masalah mendasar yang menyebabkan pengecualian Integrity API. Misalnya, aplikasi dapat meminta pengguna untuk mengupdate layanan Google Play versi lama.

Contoh UX

**Gambar 4.** Alur perbaikan error jaringan dialog GET_INTEGRITY

GET_STRONG_INTEGRITY (Kode Jenis 5)

Masalah verdict

Dialog ini dirancang untuk memperbaiki semua masalah yang sama yang ditangani oleh GET_INTEGRITY, dengan kemampuan tambahan untuk memperbaiki masalah yang mencegah perangkat menerima putusan MEETS_STRONG_INTEGRITY dan memperbaiki masalah putusan Play Protect.

Perbaikan

GET_STRONG_INTEGRITY dirancang untuk menyederhanakan pengalaman pengguna dengan menangani beberapa langkah perbaikan dalam satu alur berkelanjutan. Dialog secara otomatis memeriksa masalah integritas yang berlaku untuk alamat, termasuk:

Integritas perangkat: Jika masalah integritas perangkat terdeteksi, dialog akan memandu pengguna untuk meningkatkan status keamanan perangkat agar memenuhi persyaratan untuk verdict MEETS_STRONG_INTEGRITY.
Status Play Protect: Jika playProtectVerdict menunjukkan masalah, dialog akan memandu pengguna untuk memperbaikinya:
- Jika Play Protect dinonaktifkan (playProtectVerdict == POSSIBLE_RISK), dialog akan meminta pengguna untuk mengaktifkannya dan melakukan pemindaian semua aplikasi di perangkat.
- Jika aplikasi berbahaya terdeteksi (playProtectVerdict == MEDIUM_RISK atau HIGH_RISK), dialog akan mengarahkan pengguna untuk meng-uninstal aplikasi tersebut menggunakan Google Play Protect.
Integritas aplikasi: Jika masalah seperti akses tidak sah atau gangguan aplikasi terdeteksi, dialog akan meminta pengguna untuk mendapatkan aplikasi dari Play Store guna memperbaiki masalah tersebut.
Pengecualian sisi klien: Dialog ini juga mencoba menyelesaikan masalah mendasar yang menyebabkan pengecualian Integrity API. Misalnya, aplikasi dapat meminta pengguna untuk mengaktifkan layanan Google Play jika layanan tersebut diketahui dinonaktifkan. Pengecualian yang dapat diperbaiki adalah pengecualian Integrity API dengan kode error seperti PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR, atau PLAY_SERVICES_NOT_FOUND. Anda dapat menggunakan metode exception.isRemediable() untuk memeriksa apakah error dapat diperbaiki oleh dialog.

Contoh UX

**Gambar 5.** Dialog GET_STRONG_INTEGRITY yang mengupdate layanan Play.

Sebelumnya

Menangani kode error

Berikutnya

Alat dan dukungan tambahan

Dialog perbaikan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Meminta dialog integritas untuk memperbaiki masalah verdict

Kotlin

Java

Unity

Unreal Engine

Native

Kotlin

Java

Unity

Unreal Engine

Native

Kotlin

Java

Unity

Unreal Engine

Native

Meminta dialog integritas untuk memperbaiki pengecualian sisi klien

Kotlin

Java

Kotlin

Java

Kode dialog integritas

GET_LICENSED (Kode Jenis 1)

Masalah verdict

Perbaikan

Contoh UX

CLOSE_UNKNOWN_ACCESS_RISK (Kode Jenis 2)

Masalah verdict

Perbaikan

Contoh UX

CLOSE_ALL_ACCESS_RISK (Kode Jenis 3)

Masalah verdict

Perbaikan

Contoh UX

GET_INTEGRITY (Kode Jenis 4)

Masalah verdict

Perbaikan

Contoh UX

GET_STRONG_INTEGRITY (Kode Jenis 5)

Masalah verdict

Perbaikan

Contoh UX

Dialog perbaikan