--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0 (@captcha-la/react-native) cho Android và iOS: cài đặt, cấu hình, callback, token hết hạn, chỉ báo đang tải và xác thực phía máy chủ." --- # React Native SDK **`@captcha-la/react-native`** thêm CaptchaLa vào ứng dụng React Native trên **Android và iOS**. Phiên bản hiện tại: **1.0.0**. Đây là một lớp cầu nối mỏng trên các SDK native ([Android](./android) `la.captcha:captchala` 1.2.0 và [iOS](./ios) `CaptchalaSDK` 1.2.0): thử thách, chỉ báo đang tải và các bước kiểm tra thiết bị đều chạy ở tầng native. ## Demo trên GitHub ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/Captcha-La/react-native-demo) — ứng dụng ví dụ chạy được cho Android và iOS. ::: ## Cài đặt ```bash npm install @captcha-la/react-native cd ios && pod install ``` Autolinking thêm module native trên cả hai nền tảng. Sau đó hãy build lại ứng dụng (`npx react-native run-android` / `run-ios`); chỉ tải lại JavaScript là không đủ. SDK Android lấy từ Maven Central và SDK iOS từ CocoaPods, cả hai đều được kéo về tự động. ## Bắt đầu nhanh ```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(); ``` Luôn xác thực pass token ở backend trước khi tin tưởng nó (xem [Xác thực phía máy chủ](#server-side-validation)). ## Cấu hình `Captchala.initialize(config)`; chỉ `appKey` là bắt buộc. | Tùy chọn | Kiểu | Mặc định | Mô tả | | --- | --- | --- | --- | | `appKey` | string | — | Bắt buộc. App key của bạn trên [bảng điều khiển](https://dash.captcha.la). | | `action` | string | `"default"` | Hành động nghiệp vụ, ví dụ `"login"`, `"register"`, `"pay"`. | | `account` | string | — | Định danh tài khoản tùy chọn. | | `lang` | string | auto | Ngôn ngữ giao diện, ví dụ `"zh-CN"`, `"en"`, `"ja"`. Không đặt = ngôn ngữ thiết bị. Xem [Ngôn ngữ được hỗ trợ](../supported-languages). | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Mặc định theo hệ thống. | | `title` | string | — | Tiêu đề phía trên thử thách. | | `timeout` | number (ms) | `10000` | Thời gian chờ HTTP. | | `retryCount`, `retryDelay` | number | mặc định của SDK | Thử lại khi lỗi mạng. | | `enableVoice` | boolean | mặc định của SDK | Cung cấp thử thách bằng âm thanh. | | `enableOfflineMode` | boolean | `false` | Phương án dự phòng ngoại tuyến khi không kết nối được máy chủ. Khi đó kết quả mang `isOffline` / `isClientOnly`. | | `serverToken` | string | — | Token dùng một lần từ backend của bạn. | | `loadingStyle` | `'spinner' \| 'ring' \| 'dots' \| 'none'` | `'spinner'` | Chỉ báo trong khi thử thách đang tải. Xem [Chỉ báo đang tải](#loading-indicator). | | `loadingColor` | `'#RRGGBB'` / `'#RRGGBBAA'` | trắng | Màu chỉ báo. | | `loadingSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | Kích thước chỉ báo. | | `loadingDelay` | number (ms) | `300` | Chỉ hiển thị nếu thử thách tải lâu hơn khoảng này (`0`–`5000`). | Gọi lại `initialize()` để thay đổi cấu hình, ví dụ với một `serverToken` mới. ## API | Phương thức | Mô tả | | --- | --- | | `Captchala.initialize(config)` | Cấu hình SDK native. Gọi trước `verify()`; gọi lại sẽ thay thế cấu hình. | | `Captchala.setCallbacks(callbacks)` | Đặt các callback (đều tùy chọn). Thay thế các callback trước đó. | | `Captchala.verify()` | Hiển thị thử thách. Kết quả được trả qua các callback. | | `Captchala.dismiss()` | Đóng thử thách bằng mã. | ### Callback | Callback | Nhận | Khi nào | | --- | --- | --- | | `onReady` | — | Thử thách đã hiển thị trên màn hình. | | `onSuccess` | `{ passToken, challengeId, isOffline, isClientOnly }` | Xác minh thành công. Gửi `passToken` về backend của bạn. | | `onFail` | `{ code, message }` | Người dùng không vượt qua; họ có thể thử lại. | | `onError` | `{ code, message }` | Lỗi mạng, cấu hình hoặc hệ thống. Rẽ nhánh theo `code`; `message` là văn bản chẩn đoán tiếng Anh. | | `onClose` | — | Người dùng đã đóng thử thách. | | `onExpired` | `passToken` | Pass token hết hạn trước khi được dùng. Xem [Token hết hạn](#token-expiry). | | `onServerTokenExpired` | — | Server token bị từ chối. Trả về token mới từ backend của bạn (`Promise`) và SDK tiếp tục; trả về `null` để báo lỗi. | ## Token hết hạn {#token-expiry} Pass token nhận từ `onSuccess` chỉ có hiệu lực trong một khoảng thời gian do máy chủ quyết định. Nếu form của bạn chưa dùng nó trước khi hết hạn, `onExpired` được gọi một lần, để bạn xóa token đã lưu và yêu cầu người dùng xác minh lại thay vì gửi một token đã hết hạn: ```tsx Captchala.setCallbacks({ onSuccess: (r) => setPassToken(r.passToken), onExpired: () => { setPassToken(null); setNeedsVerify(true); // your button calls Captchala.verify() again }, }); ``` `onExpired` được gọi tối đa một lần cho mỗi lần thành công và không được gọi sau một lần `verify()` hoặc `initialize()` mới. ## Chỉ báo đang tải {#loading-indicator} Trong khi thử thách đang tải, SDK native hiển thị một chỉ báo nhỏ trên lớp nền mờ. Chỉ báo chỉ xuất hiện khi việc tải lâu hơn `loadingDelay` và biến mất khi thử thách được hiển thị. `'spinner'` (mặc định) là kiểu nan cổ điển, `'ring'` là một cung tròn xoay. Với `'none'` không có gì được hiển thị: hãy hiển thị chỉ báo của riêng bạn từ `verify()` đến `onReady`. ```tsx await Captchala.initialize({ appKey: 'YOUR_APP_KEY', loadingStyle: 'dots', loadingColor: '#3B82F6', loadingSize: 'small', loadingDelay: 500, }); ``` ## Xác thực phía máy chủ {#server-side-validation} Gửi `passToken` về backend và xác thực ở đó. Không bao giờ đặt `X-App-Secret` trong ứng dụng. ```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": "" } ``` Để cấp `serverToken` dùng một lần (tùy chọn), backend của bạn gọi `POST /v1/server/challenge/issue`. Xem [Tài liệu API](../api-reference) và [server token](../api-reference#server-token), hoặc dùng SDK máy chủ [PHP](./server-php) / [Go](./server-go). ## Khắc phục sự cố - **`The native module for '@captcha-la/react-native' is not linked`** Build lại ứng dụng sau khi cài gói. Trên iOS, hãy chạy `pod install` trong `ios/` trước. - **Build iOS không tìm thấy `CaptchalaSDK`** Chạy `pod repo update` rồi `pod install` trong `ios/`. Deployment target phải là iOS 13 trở lên. - **Android `webview_too_old`** Thử thách tương tác cần Android System WebView 63+. Xem [SDK Android](/sdk/android#webview-too-old). ## Yêu cầu - React Native 0.73+ (New Architecture và Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+