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 的可執行範例 App。
安裝
npm install @captcha-la/react-native
cd ios && pod installAutolinking 會在兩個平台上自動加入原生模組。安裝後請重新建置 App(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)。 |
若要變更設定(例如換上新的 serverToken),再次呼叫 initialize() 即可。
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 放進 App。
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 參考與 server token,或使用 PHP / Go 伺服器端 SDK。
常見問題
The native module for '@captcha-la/react-native' is not linked
安裝套件後請重新建置 App。在 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+