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 的可執行範例 App。

安裝 ​

bash
npm install @captcha-la/react-native
cd ios && pod install

Autolinking 會在兩個平台上自動加入原生模組。安裝後請重新建置 App(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)。

若要變更設定(例如換上新的 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—使用者關閉了驗證題。
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 放進 App。

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 參考與 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+

MIT-licensed examples · CaptchaLa is operated independently