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 la.captcha:captchala 1.2.0 và 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
📦
Captcha-La/react-native-demo — ứng dụng ví dụ chạy được cho Android và iOS.
Cài đặt
npm install @captcha-la/react-native
cd ios && pod installAutolinking 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
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ủ).
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. |
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ợ. |
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. |
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. |
onServerTokenExpired | — | Server token bị từ chối. Trả về token mới từ backend của bạn (Promise<string>) và SDK tiếp tục; trả về null để báo lỗi. |
Token hết hạn
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:
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
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.
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});Xác thực phía máy chủ
Gửi passToken về backend và xác thực ở đó. Không bao giờ đặt X-App-Secret trong ứng dụng.
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>" }Để 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 và server token, hoặc dùng SDK máy chủ PHP / 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ạypod installtrongios/trước.Build iOS không tìm thấy
CaptchalaSDK
Chạypod repo updaterồipod installtrongios/. 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.
Yêu cầu
- React Native 0.73+ (New Architecture và Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+