React Native SDK
@captcha-la/react-native menambahkan CaptchaLa ke aplikasi React Native di Android dan iOS. Versi saat ini: 1.0.0. Paket ini adalah jembatan tipis di atas SDK native (Android la.captcha:captchala 1.2.0 dan iOS CaptchalaSDK 1.2.0): tantangan, indikator pemuatannya, dan pemeriksaan perangkat semuanya berjalan secara native.
Demo di GitHub
📦
Captcha-La/react-native-demo — contoh aplikasi yang dapat dijalankan untuk Android dan iOS.
Instalasi
npm install @captcha-la/react-native
cd ios && pod installAutolinking menambahkan modul native di kedua platform. Setelah itu, build ulang aplikasi (npx react-native run-android / run-ios); memuat ulang JavaScript saja tidak cukup. SDK Android diambil dari Maven Central dan SDK iOS dari CocoaPods, keduanya ditarik secara otomatis.
Mulai cepat
import Captchala from '@captcha-la/react-native';
Captchala.setCallbacks({
onReady: () => {}, // the challenge is on screen
onSuccess: (r) => submit(r.passToken), // send the pass token to your backend
onFail: (e) => {}, // the user did not pass (can retry)
onError: (e) => {}, // network, configuration or system error
onClose: () => {}, // closed by the user
onExpired: () => {}, // the pass token expired: ask to verify again
onServerTokenExpired: async () => fetchServerTokenFromYourBackend(),
});
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
action: 'login',
serverToken, // one-time token from your backend, if your app requires one
});
await Captchala.verify();Selalu validasi pass token di backend Anda sebelum mempercayainya (lihat Validasi sisi server).
Konfigurasi
Captchala.initialize(config); hanya appKey yang wajib.
| Opsi | Tipe | Default | Keterangan |
|---|---|---|---|
appKey | string | — | Wajib. App key Anda dari dasbor. |
action | string | "default" | Aksi bisnis, misalnya "login", "register", "pay". |
account | string | — | Pengenal akun opsional. |
lang | string | otomatis | Bahasa UI, misalnya "zh-CN", "en", "ja". Tidak diatur = bahasa perangkat. Lihat Bahasa yang didukung. |
theme | 'auto' | 'light' | 'dark' | 'auto' | Secara default mengikuti sistem. |
title | string | — | Judul di atas tantangan. |
timeout | number (ms) | 10000 | Batas waktu HTTP. |
retryCount, retryDelay | number | default SDK | Percobaan ulang jaringan. |
enableVoice | boolean | default SDK | Menyediakan tantangan audio. |
enableOfflineMode | boolean | false | Jalur cadangan offline saat server tidak dapat dijangkau. Hasilnya kemudian membawa isOffline / isClientOnly. |
serverToken | string | — | Token sekali pakai dari backend Anda. |
loadingStyle | 'spinner' | 'ring' | 'dots' | 'none' | 'spinner' | Indikator selama tantangan dimuat. Lihat Indikator pemuatan. |
loadingColor | '#RRGGBB' / '#RRGGBBAA' | putih | Warna indikator. |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | Ukuran indikator. |
loadingDelay | number (ms) | 300 | Hanya ditampilkan jika tantangan butuh waktu lebih lama dari ini (0–5000). |
Panggil initialize() lagi untuk mengubah konfigurasi, misalnya dengan serverToken baru.
API
| Metode | Keterangan |
|---|---|
Captchala.initialize(config) | Mengonfigurasi SDK native. Panggil sebelum verify(); memanggilnya lagi akan mengganti konfigurasi. |
Captchala.setCallbacks(callbacks) | Mengatur callback (semuanya opsional). Menggantikan callback sebelumnya. |
Captchala.verify() | Menampilkan tantangan. Hasil dikirim melalui callback. |
Captchala.dismiss() | Menutup tantangan secara terprogram. |
Callback
| Callback | Menerima | Kapan |
|---|---|---|
onReady | — | Tantangan tampil di layar. |
onSuccess | { passToken, challengeId, isOffline, isClientOnly } | Terverifikasi. Kirim passToken ke backend Anda. |
onFail | { code, message } | Pengguna tidak lulus; mereka dapat mencoba lagi. |
onError | { code, message } | Error jaringan, konfigurasi, atau sistem. Bercabanglah berdasarkan code; message adalah teks diagnostik berbahasa Inggris. |
onClose | — | Pengguna menutup tantangan. |
onExpired | passToken | Pass token kedaluwarsa sebelum dipakai. Lihat Kedaluwarsa token. |
onServerTokenExpired | — | Server token ditolak. Kembalikan token baru dari backend Anda (sebuah Promise<string>) dan SDK melanjutkan; kembalikan null untuk melaporkan error. |
Kedaluwarsa token
Pass token dari onSuccess berlaku untuk waktu terbatas yang ditentukan oleh server. Jika formulir Anda belum memakainya sampai saat itu, onExpired dipanggil satu kali, sehingga Anda dapat menghapus token yang tersimpan dan meminta pengguna memverifikasi ulang alih-alih mengirim token yang sudah kedaluwarsa:
Captchala.setCallbacks({
onSuccess: (r) => setPassToken(r.passToken),
onExpired: () => {
setPassToken(null);
setNeedsVerify(true); // your button calls Captchala.verify() again
},
});onExpired dipanggil paling banyak satu kali per keberhasilan dan tidak dipanggil setelah verify() atau initialize() yang baru.
Indikator pemuatan
Selama tantangan dimuat, SDK native menampilkan indikator kecil di atas lapisan peredup. Indikator hanya muncul jika pemuatan berlangsung lebih lama dari loadingDelay dan hilang begitu tantangan ditampilkan. 'spinner' (default) adalah jari-jari klasik, 'ring' busur yang berputar. Dengan 'none' tidak ada yang ditampilkan: tampilkan indikator Anda sendiri dari verify() hingga onReady.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Validasi sisi server
Kirim passToken ke backend Anda dan validasi di sana. Jangan pernah menaruh X-App-Secret di aplikasi.
POST https://verify.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json
{ "pass_token": "<passToken>" }Untuk menerbitkan serverToken sekali pakai yang opsional, backend Anda memanggil POST /v1/server/challenge/issue. Lihat Referensi API dan server token, atau gunakan SDK server PHP / Go.
Pemecahan masalah
The native module for '@captcha-la/react-native' is not linked
Build ulang aplikasi setelah memasang paket. Di iOS, jalankan dulupod installdiios/.Build iOS tidak menemukan
CaptchalaSDK
Jalankanpod repo updatelalupod installdiios/. Deployment target harus iOS 13 atau lebih tinggi.Android
webview_too_old
Tantangan interaktif membutuhkan Android System WebView 63+. Lihat SDK Android.
Persyaratan
- React Native 0.73+ (New Architecture dan Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+