SafetyNet reCAPTCHA API

Layanan SafetyNet menyertakan reCAPTCHA API yang dapat Anda gunakan untuk melindungi aplikasi dari traffic berbahaya.

reCAPTCHA adalah layanan gratis yang menggunakan mesin analisis risiko canggih untuk melindungi aplikasi Anda dari spam dan tindakan penyalahgunaan lainnya. Jika layanan mencurigai bahwa pengguna yang berinteraksi dengan aplikasi Anda mungkin adalah bot, bukan manusia, CAPTCHA akan ditampilkan dan harus diselesaikan oleh manusia sebelum aplikasi Anda dapat terus dijalankan.

Dokumen ini menjelaskan cara mengintegrasikan reCAPTCHA API dari SafetyNet ke aplikasi Anda.

Persyaratan layanan tambahan

Dengan mengakses atau menggunakan reCAPTCHA API, Anda menyetujui Persyaratan Layanan Google API dan Persyaratan Layanan reCAPTCHA berikut. Harap baca dan pahami semua persyaratan dan kebijakan yang berlaku sebelum mengakses API.

Persyaratan Layanan reCAPTCHA

Anda menerima dan memahami bahwa reCAPTCHA API bekerja dengan mengumpulkan informasi hardware dan software, seperti data perangkat dan aplikasi, serta hasil pemeriksaan integritas, lalu mengirimkan data tersebut ke Google untuk dianalisis. Berdasarkan Pasal 3(d) Persyaratan Layanan Google API, Anda menyetujui bahwa jika Anda menggunakan API, Anda bertanggung jawab untuk menyampaikan pemberitahuan atau memberikan persetujuan apa pun yang diperlukan terkait pengumpulan dan pembagian data ini kepada Google.

Mendaftarkan pasangan kunci reCAPTCHA

Untuk mendaftarkan pasangan kunci yang akan digunakan dengan SafetyNet reCAPTCHA API, buka situs pendaftaran reCAPTCHA Android, lalu selesaikan rangkaian langkah berikut:

  1. Dalam formulir yang ditampilkan, berikan informasi berikut:

    • Label: Label unik untuk kunci Anda. Biasanya, Anda menggunakan nama perusahaan atau organisasi.
    • Jenis reCAPTCHA: Pilih reCAPTCHA v2, lalu reCAPTCHA Android.
    • Paket: Berikan nama paket untuk setiap aplikasi yang menggunakan kunci API ini. Agar aplikasi dapat menggunakan API, nama paket yang Anda masukkan harus sama persis dengan nama paket aplikasi. Masukkan setiap nama paket di barisnya masing-masing.
    • Pemilik: Tambahkan alamat email untuk setiap orang di organisasi Anda yang memantau penilaian reCAPTCHA aplikasi Anda.

  2. Centang kotak Setujui Persyaratan Layanan reCAPTCHA.

  3. Mengirim pemberitahuan kepada pemilik: Centang kotak ini jika Anda ingin menerima email tentang reCAPTCHA API, lalu klik Kirim.

  4. Di halaman yang muncul berikutnya, kunci publik dan kunci pribadi Anda akan muncul di bagian Kunci situs dan Kunci rahasia. Gunakan kunci situs saat Anda mengirim permintaan verifikasi, dan gunakan kunci rahasia saat Anda memvalidasi token respons pengguna.

Menambahkan dependensi SafetyNet API

Sebelum menggunakan reCAPTCHA API, tambahkan SafetyNet API ke project Anda. Jika Anda menggunakan Android Studio, tambahkan dependensi ini ke file Gradle level aplikasi. Untuk mengetahui informasi selengkapnya, lihat Penyiapan SafetyNet API.

Menggunakan reCAPTCHA API

Bagian ini menjelaskan cara memanggil reCAPTCHA API untuk mengirim permintaan verifikasi CAPTCHA dan menerima token respons pengguna.

Mengirim permintaan verifikasi

Untuk memanggil SafetyNet reCAPTCHA API, panggil metode verifyWithRecaptcha(). Biasanya, metode ini berkaitan dengan pemilihan elemen UI oleh pengguna, seperti tombol, dalam aktivitas Anda.

Saat menggunakan metode verifyWithRecaptcha() di aplikasi, Anda harus melakukan hal-hal berikut:

  • Memasukkan kunci situs API Anda sebagai parameter.
  • Mengganti metode onSuccess() dan onFailure() untuk menangani kedua kemungkinan hasil dari tugas permintaan verifikasi. Secara khusus, jika API meneruskan instance ApiException ke onFailure(), Anda harus menangani setiap kemungkinan kode status yang dapat diambil menggunakan getStatusCode().

Cuplikan kode berikut menunjukkan cara memanggil metode ini:

Kotlin

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

Java

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

Memvalidasi token respons pengguna

Saat reCAPTCHA API mengeksekusi metode onSuccess(), pengguna telah berhasil menyelesaikan tantangan CAPTCHA. Namun, metode ini hanya menunjukkan bahwa pengguna telah menyelesaikan CAPTCHA dengan benar. Anda masih harus memvalidasi token respons pengguna dari server backend.

Untuk mempelajari cara memvalidasi token respons pengguna, lihat Memverifikasi respons pengguna.