Mengintegrasikan reCAPTCHA Enterprise dengan aplikasi Android

Halaman ini menjelaskan cara mengintegrasikan reCAPTCHA Enterprise ke aplikasi Android Anda.

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

Sebelum memulai

Menyiapkan lingkungan Anda untuk reCAPTCHA Enterprise.
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 Google Cloud Console, lakukan langkah berikut:
  1. Buka halaman reCAPTCHA Enterprise.
    
    Buka reCAPTCHA Enterprise
  2. Dalam daftar kunci reCAPTCHA, tahan kursor ke 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

Android Asli

Siapkan lingkungan pengembangan Anda dengan mendownload dan menginstal Android Studio versi terbaru.
Pastikan Anda memiliki aplikasi dengan nilai Android SDK minimum yang ditetapkan ke API 19: Android 4.4 (KitKat). Anda dapat menetapkan SDK minimum aplikasi ke API 19 atau membuat aplikasi seluler baru.
Jika Anda membuat aplikasi seluler baru, buat aplikasi pengujian dengan memulai project Android Studio baru:
1. Pilih Empty Activity. Jika ingin menggunakan Jetpack Compose di aplikasi Anda, pilih Empty Compose Activity.
2. Tetapkan bahasa ke kotlin.
3. Tetapkan nilai SDK minimum ke API 19: Android 4.4 (KitKat).
Pastikan repositori Maven Google google() berada dalam daftar repositori pada file build.gradle level project seperti yang ditampilkan dalam cuplikan berikut:
```
allprojects {
    repositories {
        google()
    }
}
```
Untuk mengetahui informasi selengkapnya, lihat Repositori Maven Google.
Untuk menambahkan dependensi reCAPTCHA Enterprise API, tambahkan aturan build berikut ke bagian dependencies pada file build.gradle level aplikasi Anda.
```
  implementation 'com.google.android.recaptcha:recaptcha:18.5.0-beta02'
```
Untuk mengetahui informasi selengkapnya tentang menambahkan dependensi di aplikasi Android, lihat Menambahkan dependensi build.
Tambahkan izin internet di antara tag <manifest> pertama dan tag <application> pertama dalam manifes aplikasi Anda (misalnya, AndroidManifest.xml). Izin ini diperlukan karena reCAPTCHA Enterprise API melibatkan operasi jaringan.
```
<manifest ...>

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

    <application ...>
    ...
  </application>
</manifest>
```
Jika Anda ingin menggunakan library AndroidX di 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 penggunaan reCAPTCHA Enterprise melalui Flutter, lihat dokumentasi Flutter.

ReactNative

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

Mengintegrasikan reCAPTCHA Enterprise dengan aplikasi Android Anda

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

Kotlin

class MainActivity : AppCompatActivity() {

    private lateinit var recaptchaClient: RecaptchaClient

    override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.activity_main)
      initializeRecaptchaClient()
      // ... rest of onCreate code
    }

    private fun initializeRecaptchaClient() {
      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID")
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
    }

    // ... rest of activity code.
}

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    // ... rest of onCreate code
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  // ... rest of activity code.
}

Untuk setiap tindakan aplikasi Anda yang dilindungi reCAPTCHA Enterprise, panggil metode execute yang meneruskan RecaptchaAction. reCAPTCHA Enterprise 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() {
  lifecycleScope.launch {
    recaptchaClient
      .execute(RecaptchaAction.LOGIN)
      .onSuccess { token ->
        // Handle success ...
        // See "What's next" section for instructions
        // about handling tokens.
      }
      .onFailure { exception ->
        // Handle communication errors ...
        // See "Handle communication errors" section
      }
  }
}

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 communication errors ...
            // See "Handle communication errors" section
          }
        });
}

Cuplikan kode contoh berikut menunjukkan integrasi penuh metode getClient() dan execute() di satu aplikasi Aktivitas:

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  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 communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

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

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

Perhatian: getClient() dan execute() dapat memerlukan waktu beberapa detik untuk diselesaikan di perangkat. Oleh karena itu, sebaiknya lakukan hal berikut:

Lakukan inisialisasi klien saat aplikasi dimulai. Misalnya, dalam panggilan onCreate() dari class Application kustom.
Pastikan panggilan execute() tidak memblokir peristiwa UI. Mengintegrasikan execute() di aplikasi Anda tidak boleh memblokir peristiwa UI, seperti menekan tombol. Misalnya, Anda dapat memanggil execute() secara asinkron saat membuat tampilan.

Menetapkan waktu tunggu untuk panggilan API

Anda dapat menentukan nilai waktu tunggu untuk getClient dan execute API menggunakan properti timeout setiap API.

Waktu tunggu default 10 detik digunakan untuk getClient dan 10 detik untuk execute API.

Kotlin

Menyetel waktu tunggu saat memanggil getClient.

    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }

Cuplikan kode ini menetapkan waktu tunggu getClient menjadi 20 detik.

Menyetel 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 communication errors ...
          // See "Handle communication errors" section
        }
    }

Cuplikan kode ini menetapkan waktu tunggu execute menjadi 10 detik.

Java

Menyetel waktu tunggu saat memanggil getClient.

  Recaptcha
    .getTasksClient(getApplication(), "KEY_ID", 20000L)
    .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 communication errors ...
            // See "Handle communication errors" section
          }
        });

Cuplikan kode ini menetapkan waktu tunggu getClient menjadi 20 detik.

Menyetel 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 communication errors ...
            // See "Handle communication errors" section
          }
        });

Cuplikan kode ini menetapkan waktu tunggu execute menjadi 10 detik.

Menangani error komunikasi

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

Untuk 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 Anda, bukan dari perangkat seluler.