React Native SDK
@captcha-la/react-native menambah CaptchaLa pada aplikasi React Native di Android dan iOS. Versi semasa: 1.0.0. Ia ialah jambatan nipis di atas SDK asli (Android la.captcha:captchala 1.2.0 dan iOS CaptchalaSDK 1.2.0): cabaran, penunjuk pemuatannya dan semakan peranti semuanya berjalan secara asli.
Demo di GitHub
📦
Captcha-La/react-native-demo — aplikasi contoh yang boleh dijalankan untuk Android dan iOS.
Pemasangan
npm install @captcha-la/react-native
cd ios && pod installAutolinking menambah modul asli pada kedua-dua platform. Bina semula aplikasi selepas itu (npx react-native run-android / run-ios); memuat semula JavaScript sahaja tidak mencukupi. SDK Android datang daripada Maven Central dan SDK iOS daripada CocoaPods, kedua-duanya ditarik secara automatik.
Mula pantas
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();Sentiasa sahkan pass token di backend anda sebelum mempercayainya (lihat Pengesahan di pelayan).
Konfigurasi
Captchala.initialize(config); hanya appKey yang wajib.
| Pilihan | Jenis | Lalai | Keterangan |
|---|---|---|---|
appKey | string | — | Wajib. App key anda daripada papan pemuka. |
action | string | "default" | Tindakan perniagaan, contohnya "login", "register", "pay". |
account | string | — | Pengecam akaun pilihan. |
lang | string | auto | Bahasa UI, contohnya "zh-CN", "en", "ja". Tidak ditetapkan = bahasa peranti. Lihat Bahasa yang disokong. |
theme | 'auto' | 'light' | 'dark' | 'auto' | Mengikut sistem secara lalai. |
title | string | — | Tajuk di atas cabaran. |
timeout | number (ms) | 10000 | Had masa HTTP. |
retryCount, retryDelay | number | lalai SDK | Percubaan semula rangkaian. |
enableVoice | boolean | lalai SDK | Menawarkan cabaran audio. |
enableOfflineMode | boolean | false | Sandaran luar talian apabila pelayan tidak dapat dicapai. Keputusan kemudian membawa isOffline / isClientOnly. |
serverToken | string | — | Token sekali guna daripada backend anda. |
loadingStyle | 'spinner' | 'ring' | 'dots' | 'none' | 'spinner' | Penunjuk semasa cabaran dimuatkan. Lihat Penunjuk pemuatan. |
loadingColor | '#RRGGBB' / '#RRGGBBAA' | putih | Warna penunjuk. |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | Saiz penunjuk. |
loadingDelay | number (ms) | 300 | Hanya dipaparkan jika cabaran mengambil masa lebih lama daripada ini (0–5000). |
Panggil initialize() sekali lagi untuk menukar konfigurasi, contohnya dengan serverToken baharu.
API
| Kaedah | Keterangan |
|---|---|
Captchala.initialize(config) | Mengkonfigurasi SDK asli. Panggil sebelum verify(); memanggilnya semula menggantikan konfigurasi. |
Captchala.setCallbacks(callbacks) | Menetapkan panggilan balik (semuanya pilihan). Menggantikan yang terdahulu. |
Captchala.verify() | Memaparkan cabaran. Keputusan sampai melalui panggilan balik. |
Captchala.dismiss() | Menutup cabaran secara pengaturcaraan. |
Panggilan balik
| Panggilan balik | Menerima | Bila |
|---|---|---|
onReady | — | Cabaran dipaparkan pada skrin. |
onSuccess | { passToken, challengeId, isOffline, isClientOnly } | Disahkan. Hantar passToken ke backend anda. |
onFail | { code, message } | Pengguna tidak lulus; mereka boleh cuba lagi. |
onError | { code, message } | Ralat rangkaian, konfigurasi atau sistem. Bercabang berdasarkan code; message ialah teks diagnostik bahasa Inggeris. |
onClose | — | Pengguna menutup cabaran. |
onExpired | passToken | Pass token tamat tempoh sebelum digunakan. Lihat Tamat tempoh token. |
onServerTokenExpired | — | Server token ditolak. Pulangkan token baharu daripada backend anda (Promise<string>) dan SDK meneruskan; pulangkan null untuk melaporkan ralat. |
Tamat tempoh token
Pass token daripada onSuccess sah untuk tempoh terhad yang ditentukan oleh pelayan. Jika borang anda belum menggunakannya dalam tempoh itu, onExpired dipanggil sekali, supaya anda boleh mengosongkan token yang disimpan dan meminta pengguna mengesahkan semula dan bukannya menghantar token yang telah tamat tempoh:
Captchala.setCallbacks({
onSuccess: (r) => setPassToken(r.passToken),
onExpired: () => {
setPassToken(null);
setNeedsVerify(true); // your button calls Captchala.verify() again
},
});onExpired dipanggil paling banyak sekali bagi setiap kejayaan dan tidak selepas verify() atau initialize() yang baharu.
Penunjuk pemuatan
Semasa cabaran dimuatkan, SDK asli memaparkan penunjuk kecil di atas latar yang dimalapkan. Ia hanya muncul jika pemuatan mengambil masa lebih lama daripada loadingDelay dan hilang apabila cabaran dipaparkan. 'spinner' (lalai) ialah jejari klasik, 'ring' lengkok berputar. Dengan 'none' tiada apa yang dipaparkan: paparkan penunjuk anda sendiri dari verify() hingga onReady.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Pengesahan di pelayan
Hantar passToken ke backend anda dan sahkan di sana. Jangan sesekali letakkan X-App-Secret dalam 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 mengeluarkan serverToken sekali guna yang pilihan, backend anda memanggil POST /v1/server/challenge/issue. Lihat Rujukan API dan server token, atau gunakan SDK pelayan PHP / Go.
Penyelesaian masalah
The native module for '@captcha-la/react-native' is not linked
Bina semula aplikasi selepas memasang pakej. Di iOS, jalankanpod installdalamios/dahulu.Binaan iOS tidak menemui
CaptchalaSDK
Jalankanpod repo updatedan kemudianpod installdalamios/. Sasaran penggunaan mestilah iOS 13 atau lebih tinggi.Android
webview_too_old
Cabaran interaktif memerlukan Android System WebView 63+. Lihat SDK Android.
Keperluan
- React Native 0.73+ (New Architecture dan Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+