React Native SDK
@captcha-la/react-native 为 Android 和 iOS 上的 React Native 应用接入 CaptchaLa。 当前版本:1.0.0。它是原生 SDK(Android la.captcha:captchala 1.2.0 和 iOS CaptchalaSDK 1.2.0)之上的一层轻量桥接:挑战、加载指示器和设备检查都在原生层运行。
GitHub 上的示例
📦
Captcha-La/react-native-demo — 可运行的 Android / iOS 示例应用。
安装
npm install @captcha-la/react-native
cd ios && pod install自动链接(autolinking)会在两个平台上加入原生模块。安装后请重新构建应用 (npx react-native run-android / run-ios),仅重新加载 JavaScript 是不够的。Android SDK 来自 Maven Central,iOS SDK 来自 CocoaPods,都会被自动引入。
快速开始
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();信任 pass token 之前,务必先在后端校验(见服务端校验)。
配置
Captchala.initialize(config);只有 appKey 必填。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
appKey | string | — | 必填。你在控制台中的 App Key。 |
action | string | "default" | 业务动作,例如 "login"、"register"、"pay"。 |
account | string | — | 可选的账号标识。 |
lang | string | 自动 | 界面语言,例如 "zh-CN"、"en"、"ja"。不设置时使用设备语言。见支持的语言。 |
theme | 'auto' | 'light' | 'dark' | 'auto' | 默认跟随系统。 |
title | string | — | 挑战上方的标题。 |
timeout | number(毫秒) | 10000 | HTTP 超时。 |
retryCount、retryDelay | number | SDK 默认值 | 网络重试。 |
enableVoice | boolean | SDK 默认值 | 提供语音验证。 |
enableOfflineMode | boolean | false | 服务器不可达时的离线兜底。此时结果带有 isOffline / isClientOnly。 |
serverToken | string | — | 来自你后端的一次性 token。 |
loadingStyle | 'spinner' | 'ring' | 'dots' | 'none' | 'spinner' | 挑战加载期间的指示器。见加载指示器。 |
loadingColor | '#RRGGBB' / '#RRGGBBAA' | 白色 | 指示器颜色。 |
loadingSize | 'small' | 'medium' | 'large' | 'medium' | 指示器大小。 |
loadingDelay | number(毫秒) | 300 | 只有挑战加载时间超过该值才显示(0–5000)。 |
要修改配置,再次调用 initialize() 即可,例如传入新的 serverToken。
API
| 方法 | 说明 |
|---|---|
Captchala.initialize(config) | 配置原生 SDK。请在 verify() 之前调用;再次调用会替换原有配置。 |
Captchala.setCallbacks(callbacks) | 设置回调(均可选),会替换之前设置的回调。 |
Captchala.verify() | 显示挑战。结果通过回调返回。 |
Captchala.dismiss() | 以代码方式关闭挑战。 |
回调
| 回调 | 参数 | 触发时机 |
|---|---|---|
onReady | — | 挑战已显示在屏幕上。 |
onSuccess | { passToken, challengeId, isOffline, isClientOnly } | 验证通过。把 passToken 发给你的后端。 |
onFail | { code, message } | 用户未通过,可以重试。 |
onError | { code, message } | 网络、配置或系统错误。按 code 分支处理;message 是英文诊断文本。 |
onClose | — | 用户关闭了挑战。 |
onExpired | passToken | pass token 在使用前已过期。见 Token 过期。 |
onServerTokenExpired | — | server token 被拒。从你的后端返回一个新 token(Promise<string>),SDK 会继续;返回 null 则上报错误。 |
Token 过期
onSuccess 返回的 pass token 有效期有限,由服务端决定。如果表单在此之前还没用掉它, onExpired 会被调用一次,你可以借此清除保存的 token 并提示用户重新验证,而不是提交一个已过期的 token:
Captchala.setCallbacks({
onSuccess: (r) => setPassToken(r.passToken),
onExpired: () => {
setPassToken(null);
setNeedsVerify(true); // your button calls Captchala.verify() again
},
});每次成功最多调用一次 onExpired;发起新的 verify() 或调用 initialize() 之后不会再调用。
加载指示器
挑战加载期间,原生 SDK 会在遮罩上显示一个小的加载指示器。只有加载时间超过 loadingDelay 时才会出现, 挑战显示后即消失。'spinner'(默认)是经典的辐条样式,'ring' 是旋转的圆弧。设为 'none' 时不显示任何内容: 请在 verify() 到 onReady 之间显示你自己的指示器。
await Captchala.initialize({
appKey: 'YOUR_APP_KEY',
loadingStyle: 'dots',
loadingColor: '#3B82F6',
loadingSize: 'small',
loadingDelay: 500,
});服务端校验
把 passToken 发给你的后端并在后端校验。切勿把 X-App-Secret 放进应用中。
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>" }如需签发可选的一次性 serverToken,由你的后端调用 POST /v1/server/challenge/issue。 见 API 参考和服务端签发 Token,或使用 PHP / Go 服务端 SDK。
常见问题
The native module for '@captcha-la/react-native' is not linked
安装包后请重新构建应用。iOS 上请先在ios/中执行pod install。iOS 构建找不到
CaptchalaSDK
在ios/中先执行pod repo update,再执行pod install。部署目标必须为 iOS 13 或更高。Android
webview_too_old
交互式挑战需要 Android System WebView 63+。见 Android SDK。
环境要求
- React Native 0.73+(新架构与旧架构均支持)
- Android 5.0+(
minSdk 21) - iOS 13+