--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0(@captcha-la/react-native),支持 Android 与 iOS:安装、配置、回调、token 过期、加载指示器与服务端校验。" --- # React Native SDK **`@captcha-la/react-native`** 为 **Android 和 iOS** 上的 React Native 应用接入 CaptchaLa。 当前版本:**1.0.0**。它是原生 SDK([Android](./android) `la.captcha:captchala` 1.2.0 和 [iOS](./ios) `CaptchalaSDK` 1.2.0)之上的一层轻量桥接:挑战、加载指示器和设备检查都在原生层运行。 ## GitHub 上的示例 ::: tip 📦 [Captcha-La/react-native-demo](https://github.com/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` 必填。 | 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `appKey` | string | — | 必填。你在[控制台](https://dash.captcha.la)中的 App Key。 | | `action` | string | `"default"` | 业务动作,例如 `"login"`、`"register"`、`"pay"`。 | | `account` | string | — | 可选的账号标识。 | | `lang` | string | 自动 | 界面语言,例如 `"zh-CN"`、`"en"`、`"ja"`。不设置时使用设备语言。见[支持的语言](../supported-languages)。 | | `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'` | 挑战加载期间的指示器。见[加载指示器](#loading-indicator)。 | | `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 过期](#token-expiry)。 | | `onServerTokenExpired` | — | server token 被拒。从你的后端返回一个新 token(`Promise`),SDK 会继续;返回 `null` 则上报错误。 | ## Token 过期 {#token-expiry} `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()` 之后不会再调用。 ## 加载指示器 {#loading-indicator} 挑战加载期间,原生 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": "" } ``` 如需签发可选的一次性 `serverToken`,由你的后端调用 `POST /v1/server/challenge/issue`。 见 [API 参考](../api-reference)和[服务端签发 Token](../api-reference#server-token),或使用 [PHP](./server-php) / [Go](./server-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](./android#webview-too-old)。 ## 环境要求 - React Native 0.73+(新架构与旧架构均支持) - Android 5.0+(`minSdk 21`) - iOS 13+