Skip to content

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 ​

bash
npm install @captcha-la/react-native
cd ios && pod install

Autolinking 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 ​

tsx
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.

OpsiTipeDefaultKeterangan
appKeystring—Wajib. App key Anda dari dasbor.
actionstring"default"Aksi bisnis, misalnya "login", "register", "pay".
accountstring—Pengenal akun opsional.
langstringotomatisBahasa UI, misalnya "zh-CN", "en", "ja". Tidak diatur = bahasa perangkat. Lihat Bahasa yang didukung.
theme'auto' | 'light' | 'dark''auto'Secara default mengikuti sistem.
titlestring—Judul di atas tantangan.
timeoutnumber (ms)10000Batas waktu HTTP.
retryCount, retryDelaynumberdefault SDKPercobaan ulang jaringan.
enableVoicebooleandefault SDKMenyediakan tantangan audio.
enableOfflineModebooleanfalseJalur cadangan offline saat server tidak dapat dijangkau. Hasilnya kemudian membawa isOffline / isClientOnly.
serverTokenstring—Token sekali pakai dari backend Anda.
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'Indikator selama tantangan dimuat. Lihat Indikator pemuatan.
loadingColor'#RRGGBB' / '#RRGGBBAA'putihWarna indikator.
loadingSize'small' | 'medium' | 'large''medium'Ukuran indikator.
loadingDelaynumber (ms)300Hanya ditampilkan jika tantangan butuh waktu lebih lama dari ini (0–5000).

Panggil initialize() lagi untuk mengubah konfigurasi, misalnya dengan serverToken baru.

API ​

MetodeKeterangan
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 ​

CallbackMenerimaKapan
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.
onExpiredpassTokenPass 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:

tsx
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.

tsx
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.

bash
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 dulu pod install di ios/.

  • Build iOS tidak menemukan CaptchalaSDK
    Jalankan pod repo update lalu pod install di ios/. 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+

MIT-licensed examples · CaptchaLa is operated independently