Mengintegrasikan Google Cloud Fraud Defense dengan aplikasi Android

Anda dapat mengintegrasikan Google Cloud Fraud Defense ke dalam aplikasi Android untuk mengevaluasi integritas perangkat klien dan melindungi interaksi pengguna seluler yang sensitif.

SDK menggunakan refleksi dan kode dinamis untuk memungkinkan modifikasi dan penyempurnaan sistem deteksi dalam aplikasi/SDK yang sudah di-deploy. Kumpulan class yang tersedia dalam sistem dibatasi pada daftar yang dikontrol untuk menghindari gangguan pada aplikasi.

Penting: Perhatikan kebijakan penghentian penggunaan dan penonaktifan dan rencanakan untuk mengupgrade SDK secara rutin.

Sebelum memulai

1. Menyiapkan lingkungan Anda untuk Google Cloud Fraud Defense.

2. Buat Kunci reCAPTCHA untuk platform aplikasi Android.

   Atau, Anda dapat menyalin ID kunci reCAPTCHA yang ada untuk Android dengan melakukan salah satu langkah berikut:

   • Untuk menyalin ID kunci yang ada dari konsolGoogle Cloud , lakukan hal berikut:

     1. Buka halaman Google Cloud Fraud Defense.

        Buka Google Cloud Fraud Defense

     2. Pilih tab Keys.
     3. Dalam daftar kunci reCAPTCHA, temukan kunci yang ingin Anda salin, lalu klik .
   • Untuk menyalin ID kunci yang ada menggunakan REST API, gunakan metode projects.keys.list.
   • Untuk menyalin ID kunci yang ada menggunakan gcloud CLI, gunakan perintah gcloud recaptcha keys list.

Menyiapkan lingkungan Android Anda

Peringatan: Jangan bermigrasi ke Android SDK 18.2.0, karena dapat membuat aplikasi Anda tidak berfungsi karena beberapa error internal. Untuk menghindari masalah ini, lakukan migrasi langsung ke Android SDK 18.2.1 atau yang lebih baru. Untuk mengetahui detailnya, lihat laporan masalah di GitHub.

Android Asli

1. Siapkan lingkungan pengembangan Anda dengan mendownload dan menginstal Android Studio versi terbaru.

2. Pastikan Anda memiliki aplikasi dengan nilai Android SDK minimum yang ditetapkan ke API 23: Android 6.0 (Marshmallow).

3. Jika Anda membuat aplikasi seluler baru, buat aplikasi pengujian dengan memulai project Android Studio baru:

   1. Pilih Empty Activity. Jika Anda ingin menggunakan Jetpack Compose di aplikasi, pilih Empty Compose Activity.
   2. Tetapkan bahasa ke kotlin.
   3. Tetapkan nilai SDK minimum ke API 23: Android 6.0 (Marshmallow).

4. Pastikan repositori Maven Google google() ada dalam daftar repositori di file build.gradle level project seperti yang ditunjukkan dalam cuplikan berikut:

   allprojects {
       repositories {
           google()
       }
   }
   

   Untuk mengetahui informasi selengkapnya, lihat Repositori Maven Google.

5. Untuk menambahkan dependensi reCAPTCHA API, tambahkan aturan build berikut ke bagian dependencies pada file build.gradle level aplikasi Anda.

     implementation 'com.google.android.recaptcha:recaptcha:18.9.4'
   

   Untuk mengetahui informasi selengkapnya tentang cara menambahkan dependensi di aplikasi Android, lihat Menambahkan dependensi build.

6. Tambahkan izin internet di antara tag <manifest> pertama dan tag <application> pertama dalam manifes aplikasi Anda (misalnya, AndroidManifest.xml). Izin ini diperlukan karena API reCAPTCHA melibatkan operasi jaringan.

   <manifest ...>
   
       <uses-permission android:name="android.permission.INTERNET" />
   
       <application ...>
       ...
     </application>
   </manifest>
   

7. Jika Anda ingin menggunakan library AndroidX dalam project baru, kompilasi SDK ke Android 9.0 atau yang lebih tinggi dan tambahkan cuplikan kode berikut ke gradle.properties Anda.

   android.useAndroidX=true
   android.enableJetifier=true
   

   Untuk informasi selengkapnya, lihat Bermigrasi ke AndroidX.

Flutter

Untuk mengetahui petunjuk mendetail tentang cara menggunakan reCAPTCHA melalui Flutter, lihat dokumentasi Flutter.

React Native

Untuk petunjuk mendetail tentang penggunaan reCAPTCHA melalui React Native, lihat dokumentasi React Native.

Mengintegrasikan reCAPTCHA dengan aplikasi Android Anda

1. Buat instance klien menggunakan kunci reCAPTCHA (KEY_ID) yang Anda buat untuk aplikasi Android.

   Catatan: Anda hanya boleh menggunakan klien reCAPTCHA satu kali selama masa aktif aplikasi.

   Kotlin dengan fetchClient

   Metode fetchClient segera menampilkan klien dan mulai melakukan inisialisasi SDK di latar belakang. Library ini mencoba ulang komunikasi dengan server reCAPTCHA saat terjadi kegagalan jaringan.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
       // we recommend initializing in a ViewModel
       private val recaptchaScope = CoroutineScope(Dispatchers.IO)
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         recaptchaScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(this@CustomApplication, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

   Java dengan fetchClient

   public final class CustomApplication extends Application {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     public void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(this, "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 CustomApplication.this.recaptchaTasksClient = client;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 // Handle errors ...
                 // See "Handle errors" section
               }
             });
     }
   }
   

   Inisialisasi SDK dapat memerlukan waktu beberapa detik untuk selesai. Untuk mengurangi latensi ini, lakukan inisialisasi klien sedini mungkin, seperti selama panggilan onCreate() dari class Application kustom. Anda tidak boleh membuat elemen UI memblokir SDK reCAPTCHA.

   Catatan: Jika API meneruskan instance ApiException ke onFailure(), Anda harus menangani setiap kemungkinan kode status yang dapat diambil menggunakan getStatusCode(). Untuk mengetahui informasi selengkapnya, lihat Menangani error.

2. Untuk setiap tindakan aplikasi Anda yang dilindungi menggunakan reCAPTCHA, panggil metode execute yang meneruskan RecaptchaAction. Library reCAPTCHA menyediakan serangkaian tindakan bawaan dan jika perlu, Anda dapat membuat tindakan kustom.

   Cuplikan kode berikut menunjukkan cara menggunakan execute untuk melindungi tindakan LOGIN.

   Kotlin

   private fun executeLoginAction() {
     recaptchaScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle errors ...
         }
     }
   }
   

   Java

   private void executeLoginAction(View v) {
     assert recaptchaTasksClient != null;
     recaptchaTasksClient
       .executeTask(RecaptchaAction.LOGIN)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<String>() {
             @Override
             public void onSuccess(String token) {
               // Handle success ...
               // See "What's next" section for instructions
               // about handling tokens.
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               // Handle errors ...
             }
           });
   }
   

Catatan: Google Play Store mengharuskan Anda mengisi formulir keamanan data Google Play sebelum mengupload aplikasi ke Play Store. Tinjau persyaratan pengungkapan data Google Play untuk menemukan informasi yang Anda perlukan tentang reCAPTCHA Android SDK untuk mengisi formulir keamanan data.

Bermigrasi dari metode getClient ke metode fetchClient

Metode fetchClient menampilkan RecaptchaClient yang mencoba ulang inisialisasi saat terjadi kegagalan jaringan. Jika aplikasi tidak memiliki akses jaringan saat klien dibuat, klien akan terus mencoba lagi dan berhasil melakukan inisialisasi saat jaringan diperoleh.

Jika Anda memanggil execute(timeout) dan klien belum siap, klien akan mencoba melakukan inisialisasi sebelum menampilkan token atau RecaptchaErrorCode.

Contoh berikut menunjukkan cara bermigrasi dari getClient ke fetchClient.

Kotlin

// Migrate from getClient
private fun initializeWithGetClient() {
  recaptchaScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  recaptchaScope.launch {
    try {
      recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
    } catch(e: RecaptchaException){
      // Handle errors ...
    }
  }
}

Java

  // Migrate from getTasksClient
  private void initializeWithGetTasksClient() {
    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

  // Migrate to fetchTaskClient
  private void initializeWithFetchTaskClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

Menetapkan waktu tunggu untuk panggilan API

Anda dapat menentukan nilai waktu tunggu untuk execute API menggunakan properti withTimeout.

Kotlin

• Menetapkan waktu tunggu saat memanggil execute.

      recaptchaScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN, timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle errors ...
            // See "Handle errors" section
          }
      }
  

  Cuplikan kode ini menetapkan waktu tunggu execute menjadi 10 detik.

Java

• Menetapkan waktu tunggu saat memanggil execute.

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
              // See "Handle errors" section
            }
          });
  

  Cuplikan kode ini menetapkan waktu tunggu execute menjadi 10 detik.

Menangani error

Jika aplikasi Anda tidak dapat berkomunikasi dengan layanan reCAPTCHA dengan berhasil, hal itu mungkin karena API mengalami error. Anda harus menambahkan logika di aplikasi untuk menangani error tersebut dengan baik.

Untuk mengetahui detail selengkapnya tentang mitigasi error API umum, lihat RecaptchaErrorCode.

Referensi API

Untuk referensi lengkap reCAPTCHA API untuk Android, lihat com.google.android.recaptcha.

Langkah berikutnya

• Untuk menilai token respons reCAPTCHA, buat penilaian.

  Catatan: Token respons reCAPTCHA dinilai dan dianotasi dari server backend Anda, bukan dari perangkat seluler.