--- title: React Native SDK description: "CaptchaLa React Native SDK 1.0.0(@captcha-la/react-native), Android 및 iOS용: 설치, 설정, 콜백, 토큰 만료, 로딩 표시기, 서버 측 검증." --- # 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은 신뢰하기 전에 항상 백엔드에서 검증하세요([서버 측 검증](#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 | auto | UI 언어(예: `"zh-CN"`, `"en"`, `"ja"`). 지정하지 않으면 기기 언어. [지원 언어](../supported-languages) 참고. | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | 기본적으로 시스템을 따릅니다. | | `title` | string | — | 챌린지 위의 제목. | | `timeout` | number (ms) | `10000` | HTTP 타임아웃. | | `retryCount`, `retryDelay` | number | SDK 기본값 | 네트워크 재시도. | | `enableVoice` | boolean | SDK 기본값 | 음성 챌린지를 제공합니다. | | `enableOfflineMode` | boolean | `false` | 서버에 연결할 수 없을 때의 오프라인 대체 경로. 이때 결과에 `isOffline` / `isClientOnly`가 표시됩니다. | | `serverToken` | string | — | 백엔드가 발급한 일회성 토큰. | | `loadingStyle` | `'spinner' \| 'ring' \| 'dots' \| 'none'` | `'spinner'` | 챌린지를 불러오는 동안의 표시기. [로딩 표시기](#loading-indicator) 참고. | | `loadingColor` | `'#RRGGBB'` / `'#RRGGBBAA'` | 흰색 | 표시기 색상. | | `loadingSize` | `'small' \| 'medium' \| 'large'` | `'medium'` | 표시기 크기. | | `loadingDelay` | number (ms) | `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-expiry) 참고. | | `onServerTokenExpired` | — | 서버 토큰이 거부됨. 백엔드에서 새 토큰을 받아 반환하면(`Promise`) SDK가 계속 진행하고, `null`을 반환하면 오류를 보고합니다. | ## 토큰 만료 {#token-expiry} `onSuccess`로 받은 pass token은 서버가 정한 시간 동안만 유효합니다. 그때까지 폼에서 사용하지 않으면 `onExpired`가 한 번 호출되므로, 저장해 둔 토큰을 지우고 만료된 토큰을 제출하는 대신 사용자에게 다시 인증하도록 안내할 수 있습니다. ```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`은 절대 앱에 넣지 마세요. ```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)와 [서버 토큰](../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](/sdk/android#webview-too-old)를 참고하세요. ## 요구 사항 - React Native 0.73+ (New Architecture 및 Old Architecture) - Android 5.0+ (`minSdk 21`) - iOS 13+