Skip to content

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 示例应用。

安装 ​

bash
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,都会被自动引入。

快速开始 ​

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();

信任 pass token 之前,务必先在后端校验(见服务端校验)。

配置 ​

Captchala.initialize(config);只有 appKey 必填。

选项类型默认值说明
appKeystring—必填。你在控制台中的 App Key。
actionstring"default"业务动作,例如 "login"、"register"、"pay"。
accountstring—可选的账号标识。
langstring自动界面语言,例如 "zh-CN"、"en"、"ja"。不设置时使用设备语言。见支持的语言。
theme'auto' | 'light' | 'dark''auto'默认跟随系统。
titlestring—挑战上方的标题。
timeoutnumber(毫秒)10000HTTP 超时。
retryCount、retryDelaynumberSDK 默认值网络重试。
enableVoicebooleanSDK 默认值提供语音验证。
enableOfflineModebooleanfalse服务器不可达时的离线兜底。此时结果带有 isOffline / isClientOnly。
serverTokenstring—来自你后端的一次性 token。
loadingStyle'spinner' | 'ring' | 'dots' | 'none''spinner'挑战加载期间的指示器。见加载指示器。
loadingColor'#RRGGBB' / '#RRGGBBAA'白色指示器颜色。
loadingSize'small' | 'medium' | 'large''medium'指示器大小。
loadingDelaynumber(毫秒)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—用户关闭了挑战。
onExpiredpassTokenpass token 在使用前已过期。见 Token 过期。
onServerTokenExpired—server token 被拒。从你的后端返回一个新 token(Promise<string>),SDK 会继续;返回 null 则上报错误。

Token 过期 ​

onSuccess 返回的 pass token 有效期有限,由服务端决定。如果表单在此之前还没用掉它, onExpired 会被调用一次,你可以借此清除保存的 token 并提示用户重新验证,而不是提交一个已过期的 token:

tsx
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 之间显示你自己的指示器。

tsx
await Captchala.initialize({
  appKey: 'YOUR_APP_KEY',
  loadingStyle: 'dots',
  loadingColor: '#3B82F6',
  loadingSize: 'small',
  loadingDelay: 500,
});

服务端校验 ​

把 passToken 发给你的后端并在后端校验。切勿把 X-App-Secret 放进应用中。

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>" }

如需签发可选的一次性 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+

MIT-licensed examples · CaptchaLa is operated independently