--- title: React Native SDK description: "React Native SDK CaptchaLa 1.0.0 (@captcha-la/react-native) untuk Android dan iOS: instalasi, konfigurasi, callback, kedaluwarsa token, indikator pemuatan, dan validasi sisi server." --- # 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](./android) `la.captcha:captchala` 1.2.0 dan [iOS](./ios) `CaptchalaSDK` 1.2.0): tantangan, indikator pemuatannya, dan pemeriksaan perangkat semuanya berjalan secara native. ## Demo di GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/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](#server-side-validation)). ## Konfigurasi `Captchala.initialize(config)`; hanya `appKey` yang wajib. | Opsi | Tipe | Default | Keterangan | | --- | --- | --- | --- | | `appKey` | string | — | Wajib. App key Anda dari [dasbor](https://dash.captcha.la). | | `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](../supported-languages). | | `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](#loading-indicator). | | `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](#token-expiry). | | `onServerTokenExpired` | — | Server token ditolak. Kembalikan token baru dari backend Anda (sebuah `Promise`) dan SDK melanjutkan; kembalikan `null` untuk melaporkan error. | ## Kedaluwarsa token {#token-expiry} 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 {#loading-indicator} 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 {#server-side-validation} 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": "" } ``` Untuk menerbitkan `serverToken` sekali pakai yang opsional, backend Anda memanggil `POST /v1/server/challenge/issue`. Lihat [Referensi API](../api-reference) dan [server token](../api-reference#server-token), atau gunakan SDK server [PHP](./server-php) / [Go](./server-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](/sdk/android#webview-too-old). ## Persyaratan - React Native 0.73+ (New Architecture dan Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+