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용 실행 가능한 예제 앱.
설치
npm install @captcha-la/react-native
cd ios && pod installAutolinking이 두 플랫폼에 네이티브 모듈을 추가합니다. 설치 후에는 앱을 다시 빌드하세요(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 | auto | UI 언어(예: "zh-CN", "en", "ja"). 지정하지 않으면 기기 언어. 지원 언어 참고. |
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' | 챌린지를 불러오는 동안의 표시기. 로딩 표시기 참고. |
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이 사용되기 전에 만료됨. 토큰 만료 참고. |
onServerTokenExpired | — | 서버 토큰이 거부됨. 백엔드에서 새 토큰을 받아 반환하면(Promise<string>) SDK가 계속 진행하고, null을 반환하면 오류를 보고합니다. |
토큰 만료
onSuccess로 받은 pass token은 서버가 정한 시간 동안만 유효합니다. 그때까지 폼에서 사용하지 않으면 onExpired가 한 번 호출되므로, 저장해 둔 토큰을 지우고 만료된 토큰을 제출하는 대신 사용자에게 다시 인증하도록 안내할 수 있습니다.
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은 절대 앱에 넣지 마세요.
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 레퍼런스와 서버 토큰을 참고하거나 PHP / 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를 참고하세요.
요구 사항
- React Native 0.73+ (New Architecture 및 Old Architecture)
- Android 5.0+ (
minSdk 21) - iOS 13+