Mengintegrasikan reCAPTCHA dengan aplikasi Android

Halaman ini menjelaskan cara mengintegrasikan reCAPTCHA di aplikasi Android Anda.

Jika ingin memberikan tantangan visual untuk traffic yang mencurigakan, Anda dapat menggunakan SafetyNet reCAPTCHA API.

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

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

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 konsol Google Cloud, lakukan hal berikut:

     1. Buka halaman reCAPTCHA.

        Buka reCAPTCHA

     2. Di daftar kunci reCAPTCHA, arahkan kursor ke kunci yang ingin disalin, 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

Peringatan: Jangan bermigrasi ke Android SDK 18.2.0, karena dapat membuat aplikasi Anda tidak berfungsi karena beberapa error internal. Untuk menghindari masalah ini, migrasikan 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). Anda dapat menetapkan SDK minimum aplikasi ke API 19 atau membuat aplikasi seluler baru.

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 dari file build.gradle level aplikasi Anda.

     implementation 'com.google.android.recaptcha:recaptcha:18.7.0-beta01'
   

   Untuk 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 reCAPTCHA API 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 petunjuk mendetail tentang cara menggunakan reCAPTCHA melalui Flutter, lihat dokumentasi Flutter.

React Native

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

Mengintegrasikan reCAPTCHA dengan aplikasi Android

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. Fungsi ini akan mencoba lagi komunikasi dengan server reCAPTCHA saat terjadi kegagalan jaringan.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.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, lakukan inisialisasi klien sedini mungkin, seperti selama panggilan onCreate() class Application kustom. Anda tidak boleh membuat elemen UI memblokir reCAPTCHA SDK.

   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. reCAPTCHA menyediakan kumpulan 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() {
     lifecycleScope.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 kembali inisialisasi karena 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() {
  lifecycleScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  lifecycleScope.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 API execute menggunakan properti withTimeout.

Kotlin

• Tetapkan waktu tunggu saat memanggil execute.

      lifecycleScope.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

• Tetapkan 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 berhasil melakukan komunikasi dengan layanan reCAPTCHA, 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 untuk error API umum, lihat RecaptchaErrorCode.

Referensi API

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

Langkah selanjutnya

• Untuk menilai token respons reCAPTCHA, buat penilaian.

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