Panduan Integrasi CAPTCHA Android

Pengenalan Produk

Item	Deskripsi
Fitur Utama	CAPTCHA generasi terbaru yang secara cerdas menangani kerugian bisnis dan risiko keamanan akibat serangan otomatis dari skrip.
Kebijakan Privasi SDK	Kebijakan
Panduan Kepatuhan SDK	Panduan
Tautan Unduh SDK	Unduh

Persyaratan Lingkungan

Item	Sumber Daya
Target Pengembangan	`Android 5.0+` (minSdk 21)
Lingkungan Pengembangan	`Android Studio 2020.3.1 Arctic Fox+`
Alat Build	`Gradle` (Android Gradle Plugin 7+)
Ketergantungan Sistem	Tidak ada
Ketergantungan Pihak Ketiga SDK	Tidak ada
Penambahan Paket	SDK terverifikasi: 60K

Integrasi SDK

Mengimpor SDK

Seret file .aar (misal engagelab_captcha_android_vx.y.z.aar) dari paket zip ke folder libs pada proyek Anda. Setelah itu, pastikan file .aar sudah ditambahkan ke Library. Tambahkan kode berikut ke file build.gradle proyek Anda:

repositories { flatDir { dirs 'libs' } }

              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

Tampilkan blok kode ini di jendela mengambang

Tambahkan juga paket aar secara manual sebagai dependensi:

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

              
              implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

Tampilkan blok kode ini di jendela mengambang

Konfigurasi untuk Proyek Non-Kotlin

Pada build.gradle di root proyek:

ext.kotlin_version = "1.6.22" dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" }

              
              ext.kotlin_version = "1.6.22"

dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

Tampilkan blok kode ini di jendela mengambang

Pada build.gradle modul:

apply plugin: 'kotlin-android' dependencies { implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" }

              
              apply plugin: 'kotlin-android'
dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

Tampilkan blok kode ini di jendela mengambang

Jika terjadi konflik versi kotlin, kecualikan dependensi kotlin: exclude(group: 'org.jetbrains.kotlin')

Menambahkan Izin

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

              
              <!--Wajib - Aplikasi default-->
<uses-permission android:name="android.permission.INTERNET" />
<!--Untuk kompatibilitas API level di bawah 23 (misal Android 4.x dan 5.x)-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Tampilkan blok kode ini di jendela mengambang

Aturan Proguard

Paket aar SDK sudah di-obfuscate. Jangan lakukan obfuscasi ganda. Secara default, konfigurasi obfuscasi SDK sudah disertakan. Jika Anda mengekstrak aar dan mengintegrasikan file jar serta resource secara terpisah, salin isi file proguard.txt dari hasil ekstraksi ke konfigurasi obfuscation aplikasi Anda.

Jika menggunakan andRes untuk obfuscasi resource, kecualikan resource SDK berikut:

"R.string.gt4_*", "R.style.gt4_*",

              
              "R.string.gt4_*",
"R.style.gt4_*",

Tampilkan blok kode ini di jendela mengambang

Konfigurasi Antarmuka

Logika Pemanggilan

Konfigurasi Inisialisasi
Mulai Verifikasi
Dapatkan Callback Verifikasi
Hancurkan Resource

Lihat Proses Struktur Produk untuk verifikasi perilaku. Siapkan antarmuka sisi server di backend Anda dan konfigurasikan captchaId serta Key dari Konsol Manajemen EngageLab.

Inisialisasi

Konfigurasi inisialisasi SDK dapat ditempatkan di dalam onCreate atau onCreateView.

Metode:

public static GTCaptcha4Client getClient(Context context); public GTCaptcha4Client init(String captchaId); public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

              
              public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

Tampilkan blok kode ini di jendela mengambang

Parameter	Tipe	Deskripsi
context	Context	Objek Context, wajib instance Activity
appId	String	APP_ID, parameter wajib
config	GTCaptcha4Config	Objek konfigurasi, opsional

Memanggil init() akan memulai preloading. Disarankan inisialisasi di onCreate atau onCreateView.

Mulai Verifikasi

Memulai proses verifikasi.

Metode:

public void verifyWithCaptcha();

              
              public void verifyWithCaptcha();

Tampilkan blok kode ini di jendela mengambang

Batalkan Verifikasi

Membatalkan proses verifikasi dan menutup jendela verifikasi.

Metode:

public void cancel();

              
              public void cancel();

Tampilkan blok kode ini di jendela mengambang

Aktif/Nonaktifkan Monitoring Log

Metode:

public void setLogEnable(boolean enable);

              
              public void setLogEnable(boolean enable);

Tampilkan blok kode ini di jendela mengambang

Mendapatkan Callback Verifikasi

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener); public GTCaptcha4Client addOnFailureListener(OnFailureListener listener); public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

              
              public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

Tampilkan blok kode ini di jendela mengambang

Contoh Kode:

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Aktifkan verifikasi sekunder }else { // TODO Verifikasi jawaban pengguna gagal } } }).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() { @Override public void onWebViewShow() { } });

              
              gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
            // TODO Aktifkan verifikasi sekunder
        }else {
            // TODO Verifikasi jawaban pengguna gagal
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
      @Override
      public void onWebViewShow() {
      }
  });

Tampilkan blok kode ini di jendela mengambang

Hancurkan Resource

Panggil pada siklus hidup onDestroy:

public void onDestroy(){ super.onDestroy(); if(gtCaptcha4Client != null){ gtCaptcha4Client.destroy(); } }

              
              public void onDestroy(){
    super.onDestroy();
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}

Tampilkan blok kode ini di jendela mengambang

Perubahan Orientasi Layar

@Override public void onConfigurationChanged(Configuration newConfig) { super.onConfigurationChanged(newConfig); if(gtCaptcha4Client != null){ gtCaptcha4Client.configurationChanged(newConfig); } }

              
              @Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

Tampilkan blok kode ini di jendela mengambang

Contoh Kode Preload

@Override public void onViewCreated(View view, Bundle savedInstanceState){ super.onViewCreated(view, savedInstanceState); String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO Nonaktifkan di produksi .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config); } private void click(){ gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Aktifkan verifikasi sekunder }else { // TODO Verifikasi jawaban pengguna gagal } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              @Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO Nonaktifkan di produksi
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config);
}

private void click(){
    gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO Aktifkan verifikasi sekunder
                    }else {
                        // TODO Verifikasi jawaban pengguna gagal
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

Tampilkan blok kode ini di jendela mengambang

Contoh Kode Loading Normal

private void click(){ String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO Nonaktifkan di produksi .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config) .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Aktifkan verifikasi sekunder }else { // TODO Verifikasi jawaban pengguna gagal } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              private void click(){
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO Nonaktifkan di produksi
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config)
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO Aktifkan verifikasi sekunder
                    }else {
                        // TODO Verifikasi jawaban pengguna gagal
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

Tampilkan blok kode ini di jendela mengambang

Untuk contoh kode lebih lengkap, silakan lihat Demo resmi.

Konfigurasi Parameter

Konfigurasikan parameter melalui GTCaptcha4Config.Builder:

Definisi	Deskripsi
`setResourcePath`	Wajib: https://captcha-stat.engagelab.com/www/gt4-index.html
`setApiServers`	Wajib: captcha-api.engagelab.com
`setStaticServers`	Wajib: captcha-stat.engagelab.com/www/js
`setParams`	Parameter tambahan untuk frontend `js`
`setDebug`	Aktifkan mode debug, default `false`, set ke `false` di produksi
`setLanguage`	Bahasa, default mengikuti aplikasi
`setCanceledOnTouchOutside`	Tutup saat disentuh di luar, default `true`
`setTimeOut`	Timeout dalam ms, default 10000
`setBackgroundColor`	Warna latar belakang, default transparan
`setDialogStyle`	Tema dialog, default `gt4_captcha_dialog_style`
`setDialogShowListener`	Callback saat jendela verifikasi tampil
`build`	Membuat objek `GTCaptcha4Config`

Parameter tambahan dapat diatur melalui setParams sesuai dokumentasi API.

setParams hanya menerima tipe data dasar, string, dan JSONArray.

Penanganan Error

Kesalahan bisa terjadi selama proses verifikasi. Tangani dengan mengimplementasikan addOnFailureListener:

Catatan: Callback error termasuk pembatalan oleh pengguna, bisa difilter terpisah.

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error){ // Contoh error: // {"code":"-14460","msg":"Sesi verifikasi dibatalkan","desc":{"description":"Pengguna membatalkan 'Captcha'"}} // Anda dapat parsing error sebagai JSON, menampilkan deskripsi error, dan kode error Toast.makeText(context, "Kesalahan Verifikasi: " + error, Toast.LENGTH_SHORT).show(); } });

              
              gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error){
        // Contoh error:
        // {"code":"-14460","msg":"Sesi verifikasi dibatalkan","desc":{"description":"Pengguna membatalkan 'Captcha'"}}
        // Anda dapat parsing error sebagai JSON, menampilkan deskripsi error, dan kode error
        Toast.makeText(context, "Kesalahan Verifikasi: " + error, Toast.LENGTH_SHORT).show();
    }
});

Tampilkan blok kode ini di jendela mengambang

Sangat disarankan untuk menampilkan kode error dan alasan error ke pengguna agar memudahkan troubleshooting online.

Lihat daftar kode error di: Daftar Kode Error