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 dalam aplikasi Anda.

Persyaratan layanan tambahan

Dengan mengakses atau menggunakan reCAPTCHA API, Anda menyetujui Persyaratan Layanan Google API, dan Persyaratan Tambahan 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 setuju 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:

Dalam formulir yang ditampilkan, berikan informasi berikut:
- Label: Label unik untuk kunci Anda. Biasanya, Anda menggunakan nama perusahaan atau organisasi.
- Nama Paket: Berikan nama paket untuk setiap aplikasi yang menggunakan kunci API ini. Agar aplikasi dapat menggunakan API ini, nama paket yang Anda masukkan harus sama persis dengan nama paket untuk aplikasi tersebut. Masukkan setiap nama paket pada barisnya masing-masing.
- Mengirim pemberitahuan ke pemilik: Centang kotak ini jika Anda ingin menerima email tentang reCAPTCHA API.
Centang kotak Setujui Persyaratan Layanan reCAPTCHA, lalu klik Daftar.
Di bagian Menambahkan reCAPTCHA ke aplikasi Anda di halaman yang muncul berikutnya, kunci publik dan pribadi Anda akan muncul di bawah 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, Anda perlu menambahkan SafetyNet API ke project Anda. Jika menggunakan Android Studio dan ingin mengompilasi API ini ke dependensi Gradle secara selektif, Anda harus menyertakan aturan build yang ditampilkan dalam cuplikan kode berikut:

    apply plugin: 'com.android.application'
    ...
    dependencies {
        compile 'com.google.android.gms:play-services-safetynet:17.0.0'
    }

Untuk informasi selengkapnya, lihat Menyiapkan Layanan Google Play.

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

Memasukkan kunci situs API Anda sebagai parameter.
Ganti 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(). Untuk informasi selengkapnya, lihat Menangani error komunikasi.

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 memecahkan CAPTCHA dengan benar. Anda masih harus memvalidasi token respons pengguna dari server backend.

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

Menangani error komunikasi

Jika aplikasi Anda tidak berhasil melakukan komunikasi dengan layanan reCAPTCHA, hal itu kemungkinan karena API mengalami error. Anda harus menambahkan logika ke dalam aplikasi untuk menangani error tersebut dengan baik. Selain itu, saat error terjadi, aplikasi Anda akan menampilkan pesan kepada pengguna yang menjelaskan mengapa respons CAPTCHA mereka tidak dapat diproses.

Daftar berikut menampilkan kode status untuk error API yang paling umum:

RECAPTCHA_INVALID_SITEKEY

Kunci situs tidak valid. Pastikan Anda telah mendaftarkan kunci API dengan sukses dan telah menyalin kunci situs dengan benar sebagai parameter saat memanggil API.

Nilai konstanta: 12007

RECAPTCHA_INVALID_KEYTYPE

Jenis kunci situs tidak valid. Buat kunci situs baru dengan membuka situs pendaftaran reCAPTCHA Android.

Nilai konstanta: 12008

RECAPTCHA_INVALID_PACKAGE_NAME

Nama paket aplikasi pemanggil tidak cocok dengan nama apa pun yang Anda kaitkan dengan kunci situs. Tambahkan nama paket aplikasi pemanggil ke kunci situs di reCAPTCHA Admin Console, atau nonaktifkan validasi nama paket untuk kunci situs Anda.

Nilai konstanta: 12013

UNSUPPORTED_SDK_VERSION

API tidak didukung pada versi Android SDK perangkat. Upgrade ke Android SDK versi baru, lalu cobalah berkomunikasi kembali dengan API.

Nilai konstanta: 12006

TIMEOUT

Waktu sesi habis selagi API menunggu respons, entah karena pengguna tidak berinteraksi dengan CAPTCHA atau karena waktu untuk memuat CAPTCHA itu sendiri sudah habis. Tunggu sampai pengguna memanggil API lagi. Sementara itu, Anda dapat memberi tahu pengguna bahwa mereka harus menyelesaikan CAPTCHA agar dapat terus menggunakan aplikasi Anda.

Nilai konstanta: 15

NETWORK_ERROR

Tidak ada koneksi Internet. Setelah memastikan konektivitas, cobalah berkomunikasi kembali dengan API.

Nilai konstanta: 7

ERROR

Operasi mengalami kegagalan umum.

Nilai konstanta: 13

Untuk detail selengkapnya tentang kode status yang dapat ditampilkan oleh reCAPTCHA API, lihat referensi SafetyNetStatusCodes.