--- 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 的可執行範例 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 之前,務必先在你的後端驗證(見[伺服器端驗證](#server-side-validation))。 ## 設定 `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`)。 | 若要變更設定(例如換上新的 `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 過期](#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, }); ``` ## 伺服器端驗證 {#server-side-validation} 將 `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": "" } ``` 若要簽發選用的一次性 `serverToken`,由你的後端呼叫 `POST /v1/server/challenge/issue`。請見 [API 參考](../api-reference)與 [server token](../api-reference#server-token),或使用 [PHP](./server-php) / [Go](./server-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](./android)。 ## 系統需求 - React Native 0.73+(新架構與舊架構皆可) - Android 5.0+(`minSdk 21`) - iOS 13+