Skip to content

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 ​

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ủ).

Cấu hình ​

Captchala.initialize(config); chỉ appKey là bắt buộc.

Tùy chọnKiểuMặc địnhMô tả
appKeystring—Bắt buộc. App key của bạn trên bảng điều khiển.
actionstring"default"Hành động nghiệp vụ, ví dụ "login", "register", "pay".
accountstring—Định danh tài khoản tùy chọn.
langstringautoNgô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.
titlestring—Tiêu đề phía trên thử thách.
timeoutnumber (ms)10000Thời gian chờ HTTP.
retryCount, retryDelaynumbermặc định của SDKThử lại khi lỗi mạng.
enableVoicebooleanmặc định của SDKCung cấp thử thách bằng âm thanh.
enableOfflineModebooleanfalsePhươ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.
serverTokenstring—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ắngMàu chỉ báo.
loadingSize'small' | 'medium' | 'large''medium'Kích thước chỉ báo.
loadingDelaynumber (ms)300Chỉ 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ứcMô 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 ​

CallbackNhậnKhi 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.
onExpiredpassTokenPass 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:

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 ​

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ủ ​

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": "<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ạ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.

Yêu cầu ​

  • React Native 0.73+ (New Architecture và Old Architecture)
  • Android 5.0+ (minSdk 21)
  • iOS 13+

MIT-licensed examples · CaptchaLa is operated independently