--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0 (@captcha-la/react-native) untuk Android dan iOS: pemasangan, konfigurasi, panggilan balik, tamat tempoh token, penunjuk pemuatan dan pengesahan di pelayan." --- # 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](./android) `la.captcha:captchala` 1.2.0 dan [iOS](./ios) `CaptchalaSDK` 1.2.0): cabaran, penunjuk pemuatannya dan semakan peranti semuanya berjalan secara asli. ## Demo di GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/Captcha-La/react-native-demo) — aplikasi contoh yang boleh dijalankan untuk Android dan iOS. ::: ## Pemasangan ```bash npm install @captcha-la/react-native cd ios && pod install ``` Autolinking 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 ```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(); ``` Sentiasa sahkan pass token di backend anda sebelum mempercayainya (lihat [Pengesahan di pelayan](#server-side-validation)). ## Konfigurasi `Captchala.initialize(config)`; hanya `appKey` yang wajib. | Pilihan | Jenis | Lalai | Keterangan | | --- | --- | --- | --- | | `appKey` | string | — | Wajib. App key anda daripada [papan pemuka](https://dash.captcha.la). | | `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](../supported-languages). | | `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](#loading-indicator). | | `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](#token-expiry). | | `onServerTokenExpired` | — | Server token ditolak. Pulangkan token baharu daripada backend anda (`Promise`) dan SDK meneruskan; pulangkan `null` untuk melaporkan ralat. | ## Tamat tempoh token {#token-expiry} 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: ```tsx 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 {#loading-indicator} 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`. ```tsx await Captchala.initialize({ appKey: 'YOUR_APP_KEY', loadingStyle: 'dots', loadingColor: '#3B82F6', loadingSize: 'small', loadingDelay: 500, }); ``` ## Pengesahan di pelayan {#server-side-validation} Hantar `passToken` ke backend anda dan sahkan di sana. Jangan sesekali letakkan `X-App-Secret` dalam 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": "" } ``` Untuk mengeluarkan `serverToken` sekali guna yang pilihan, backend anda memanggil `POST /v1/server/challenge/issue`. Lihat [Rujukan API](../api-reference) dan [server token](../api-reference#server-token), atau gunakan SDK pelayan [PHP](./server-php) / [Go](./server-go). ## Penyelesaian masalah - **`The native module for '@captcha-la/react-native' is not linked`** Bina semula aplikasi selepas memasang pakej. Di iOS, jalankan `pod install` dalam `ios/` dahulu. - **Binaan iOS tidak menemui `CaptchalaSDK`** Jalankan `pod repo update` dan kemudian `pod install` dalam `ios/`. Sasaran penggunaan mestilah iOS 13 atau lebih tinggi. - **Android `webview_too_old`** Cabaran interaktif memerlukan Android System WebView 63+. Lihat [SDK Android](/sdk/android#webview-too-old). ## Keperluan - React Native 0.73+ (New Architecture dan Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+