Mengintegrasikan reCAPTCHA dengan aplikasi Android

Halaman ini menjelaskan cara mengintegrasikan reCAPTCHA di aplikasi Android Anda.

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

Sebelum memulai

1. Siapkan lingkungan Anda untuk reCAPTCHA.

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 langkah-langkah berikut:

     1. Buka halaman reCAPTCHA.

        Buka reCAPTCHA

     2. Di daftar kunci reCAPTCHA, arahkan kursor ke kunci yang ingin Anda salin, lalu klik content_copy .
   • 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

Mengintegrasikan reCAPTCHA dengan aplikasi Android Anda

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

   Kotlin dengan fetchClient

   Metode fetchClient segera menampilkan klien dan mulai menginisialisasi SDK di latar belakang. Library ini mencoba ulang komunikasi dengan server reCAPTCHA jika 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(application, "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
     protected void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(getApplication(), "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 MainActivity.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, inisialisasi klien sedini mungkin, seperti selama panggilan onCreate() class Application kustom. Anda tidak boleh membuat elemen UI memblokir reCAPTCHA SDK.

2. Untuk setiap tindakan aplikasi yang dilindungi menggunakan reCAPTCHA, panggil metode execute dengan meneruskan RecaptchaAction. 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 ...
             }
           });
   }
   

Bermigrasi dari metode getClient ke metode fetchClient

Metode fetchClient menampilkan RecaptchaClient yang mencoba ulang inisialisasi jika terjadi kegagalan jaringan. Jika aplikasi tidak memiliki akses jaringan saat klien dibuat, klien akan terus mencoba lagi dan berhasil diinisialisasi 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.

// 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 ...
    }
  }
}

  // 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 API execute menggunakan properti withTimeout.

Menangani error

Jika aplikasi Anda tidak berhasil melakukan komunikasi dengan layanan reCAPTCHA, hal itu mungkin karena API mengalami error. Anda harus menambahkan logika ke dalam aplikasi untuk menangani error tersebut dengan baik.

Untuk mengetahui detail selengkapnya tentang mitigasi untuk 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.