HarmonyOS SDK
HarmonyOS NEXT(API 12 / HarmonyOS 5.0.0 이상) 용 ArkTS SDK로, 단일 .har(@captchala/captchala)로 배포됩니다. 현재 버전은 1.2.0입니다. 검증 흐름은 Android·iOS SDK와 같습니다. CAPTCHA가 현재 페이지 위에 대화상자로 열리고, 반환된 passToken을 백엔드에서 검증합니다.
INFO
HarmonyOS 4.x 이하는 Android 앱을 실행합니다. 이 경우 Android SDK를 사용하세요.
설치
SDK는 ohpm에 게시되어 있지 않습니다. 대시보드에서 HAR를 내려받아 로컬 의존성으로 추가합니다.
- 대시보드에 로그인하고 SDK 다운로드를 엽니다. 같은 페이지에서 DevEco Studio로 열 수 있는 HarmonyOS 데모 프로젝트(소스)도 받을 수 있습니다.
- HarmonyOS HAR(예:
captchala-1.2.0.har)를 내려받습니다. - 파일의 SHA-256을 다운로드 페이지에 표시된 값과 비교합니다. 다르면 해당 파일을 사용하지 마세요.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- 파일을
entry/libs/에 복사하고entry/oh-package.json5에 추가합니다.
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}entry디렉터리에서ohpm install을 실행하거나 DevEco Studio에서 Sync Now를 클릭합니다.
cd entry
ohpm installHAR는 난독화된 릴리스 빌드이며 아래에 나열한 공개 API만 노출합니다. 사용 측 난독화 규칙이 HAR에 포함되어 있으므로 릴리스 빌드에 keep 규칙을 추가할 필요가 없습니다.
권한
SDK는 ohos.permission.INTERNET 권한 하나만 사용하며, 런타임 권한을 요청하거나 묻지 않습니다. entry 모듈에 선언되어 있는지 확인하세요.
// entry/src/main/module.json5
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}
}업그레이드
새 HAR를 내려받아 entry/libs/에 복사하고, entry/oh-package.json5의 file: 경로에 있는 버전을 바꾼 뒤 이전 .har를 삭제하고 ohpm install을 다시 실행합니다.
빠른 시작
전체 흐름:
- 백엔드가 로그인한 사용자용 일회성
server_token을 발급합니다(Server token 참고). - 앱이 이를 SDK에 전달하고 CAPTCHA를 엽니다.
onSuccess가passToken을 반환하면 앱이 이를 백엔드로 보냅니다.- 백엔드가
passToken을 검증합니다(서버 측 검증 참고).
import {
CaptchalaClient,
CaptchalaConfigBuilder,
CaptchalaListener,
CaptchalaResult,
CaptchalaError
} from '@captchala/captchala';
@Entry
@Component
struct Login {
private async verify(): Promise<void> {
// 1. Fetch a one-shot server_token from YOUR backend
// (which calls the CaptchaLa server API with X-App-Key + X-App-Secret).
const serverToken: string | null = await fetchServerTokenFromYourBackend();
// 2. Listen for terminal events.
const listener: CaptchalaListener = {
onReady: (): void => { /* challenge presented */ },
onSuccess: (result: CaptchalaResult): void => {
// Send result.passToken to your backend for validation.
sendToBackend(result.passToken);
},
onFail: (error: CaptchalaError): void => { /* wrong answer, the user may retry */ },
onError: (error: CaptchalaError): void => { /* network / configuration error */ },
onClose: (): void => { /* user dismissed */ },
onExpired: (passToken: string): void => { /* the pass token expired: ask the user to verify again */ }
};
// 3. Build the config.
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setAction('login') // login, register, pay, …
// .setLang('ja') // optional: default is the device language
// .setTheme('light') // optional: 'auto' (default, follows the system) | 'light' | 'dark'
.setServerToken(serverToken)
.setOnServerTokenExpired(() => fetchServerTokenFromYourBackend())
.build();
// 4. Open the CAPTCHA. The result is delivered through the listener.
CaptchalaClient.getClient(this.getUIContext())
.init(config)
.setListener(listener)
.verify();
}
build() {
Button('Verify').onClick(() => { this.verify(); })
}
}Server token
server_token은 앱이 아니라 백엔드가 X-App-Key + X-App-Secret으로 /v1/server/challenge/issue를 호출해 발급합니다. 자체 사용자 ID를 bind_uid로 전달하면 토큰과 그로부터 나온 passToken이 해당 사용자에게 귀속됩니다.
POST https://verify.captcha.la/v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded
action=login&ttl=300&max_uses=1&bind_uid=user_12345{
"code": 0,
"data": {
"server_token": "sct_xxxxxxxxxxxx",
"expires_in": 300,
"issued_at": 1713600000
}
}data.server_token(접두사 sct_)을 앱에 반환합니다. action은 setAction에 전달한 값과 같아야 합니다. setOnServerTokenExpired를 설정하면 챌린지 도중 토큰이 거부될 때 SDK가 자동으로 새 토큰을 받아 재시도합니다. null을 반환하면 원래 오류가 그대로 전달됩니다.
신원 바인딩 옵션(bind_uid, bind_ip)은 토큰을 발급할 때 서버에서만 지정합니다. 앱은 이 값을 보내지 않습니다. 전체 파라미터는 API 레퍼런스를 참고하거나 PHP / Go 서버 SDK를 사용하세요.
주요 API
| 심볼 | 용도 |
|---|---|
CaptchalaClient.getClient(uiContext) | 싱글턴 진입점으로, 페이지의 UIContext에 연결됩니다. |
CaptchalaConfigBuilder | 설정용 빌더(아래 표 참고). build()는 CaptchalaConfig를 반환합니다. |
init(config) | 설정을 적용합니다. client를 반환하므로 체이닝할 수 있습니다. |
setListener(listener) | CaptchalaListener를 등록합니다. onSuccess만 필수이며 onReady, onFail, onError, onClose, onExpired(토큰 만료 참고)는 선택입니다. |
verify() | CAPTCHA 대화상자를 엽니다. 결과는 listener로 전달됩니다. |
refresh() / cancel() / dismiss() | 현재 챌린지 새로고침 / 흐름 중단 후 대화상자 닫기 / 대화상자 닫기. |
CaptchalaClient.destroy() | 싱글턴을 해제합니다. |
CaptchalaResult | passToken, challengeId, ttl, isOffline, isClientOnly. passToken을 백엔드로 보냅니다. ttl은 1.2.0부터 사용 중단되었습니다. 토큰 수명은 서버가 정하며 바뀔 수 있으므로 onExpired를 사용하세요. |
CaptchalaError | code, message, detail. onFail(사용자가 재시도 가능)과 onError(네트워크·설정·시스템 오류)에 전달됩니다. |
const client = CaptchalaClient.getClient(this.getUIContext());
client.refresh(); // reload the current challenge
client.cancel(); // stop the flow and close the dialog
client.dismiss(); // close the dialog
CaptchalaClient.destroy(); // release the singleton설정
| 메서드 | 기본값 | 설명 |
|---|---|---|
setAppKey(string) | 필수 | 대시보드의 App Key. |
setAction(string) | default | 비즈니스 액션(login, register, pay 등). server_token의 action과 같아야 합니다. |
setLang(string) | '' (auto) | 챌린지 언어(예: en, zh-CN). |
setTheme(string) | auto | auto(시스템을 따름), light 또는 dark. |
setServerToken(string | null) | null | 백엔드가 발급한 server_token. |
setOnServerTokenExpired(cb) | null | 백엔드에서 새 server_token을 가져오는 () => Promise<string | null>. |
setTimeout(number) | 10000 | 요청 타임아웃(ms). |
setEnableVoice(boolean) | true | 음성 챌린지를 제공합니다. |
setEnableOfflineMode(boolean) | false | 장애 시 대체 경로를 허용합니다. 결과에 isOffline / isClientOnly가 표시됩니다. |
setMaskClosable(boolean) | false | 배경을 탭하면 대화상자가 닫힙니다. |
setCollectOdid(boolean) | true | 기기 ODID의 해시를 전송합니다(개인정보 참고). |
setLoadingStyle(string) | 'spinner' | 로딩 표시기. 로딩 표시기 참고. |
setLoadingColor(string | null) | 흰색 | 표시기 색상, #RRGGBB 또는 #RRGGBBAA. |
setLoadingSize(string) | 'medium' | 'small', 'medium' 또는 'large'. |
setLoadingDelay(number) | 300 | 표시기가 나타나기 전까지의 밀리초, 0–5000. |
setDebug(boolean) | false | 개발 중 상세 로그. |
토큰 만료
onSuccess로 받은 pass token은 서버가 정한 시간 동안만 유효합니다. 그때까지 페이지에서 사용하지 않으면 listener의 onExpired(passToken)이 한 번 호출됩니다. 저장해 둔 토큰을 지우고, 만료된 토큰을 제출하는 대신 사용자에게 다시 인증하도록 안내하세요. 새 인증은 verify()로 시작합니다.
const listener: CaptchalaListener = {
onSuccess: (result: CaptchalaResult): void => { this.passToken = result.passToken; },
onExpired: (passToken: string): void => {
this.passToken = '';
this.showVerifyAgain = true; // your button calls client.verify() again
}
};새 verify(), init() 또는 destroy() 이후에는 onExpired가 호출되지 않습니다. 1.2.0부터 사용할 수 있습니다.
로딩 표시기
챌린지를 불러오는 동안 SDK는 어둡게 처리된 배경 위에 작은 표시기를 보여 줍니다. 로딩이 setLoadingDelay보다 오래 걸릴 때만 나타나며 챌린지가 표시되면 사라집니다. 1.2.0부터 사용할 수 있습니다.
setLoadingStyle:'spinner'(기본값, 살),'ring'(회전하는 호),'dots'또는'none'.'none'이면 아무것도 표시하지 않으므로verify()부터onReady까지 직접 만든 표시기를 보여 주세요.setLoadingColor:#RRGGBB또는#RRGGBBAA, 기본값은 흰색.setLoadingSize:'small','medium'(기본값) 또는'large'.setLoadingDelay: 밀리초,0–5000.
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setLoadingStyle('dots')
.setLoadingColor('#3B82F6')
.setLoadingSize('small')
.setLoadingDelay(500)
.build();서버 측 검증
result.passToken을 백엔드로 전달해 CaptchaLa API로 검증합니다. 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": "<result.passToken>", "expected_action": "login" }data.valid가 true이고 data.uid가 server_token을 발급한 사용자와 같을 때만 요청을 허용합니다. 토큰은 한 번만 사용할 수 있습니다. 전체 응답과 오류 코드는 API 레퍼런스를 참고하세요.
개인정보
SDK는 권한이 필요 없는 기기 속성(모델, OS 버전, 화면, 로캘, 시간대 등)을 읽어 검증과 부정 행위 방지에만 사용합니다. 기본적으로 기기 ODID의 SHA-256 해시(잘라낸 값)도 전송하며 원본 값은 보내지 않습니다. OAID, UDID, 일련번호, 계정 데이터는 수집하지 않습니다. ODID 해시를 끄려면:
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setCollectOdid(false) // the ODID is never read
.build();켜 둔다면 개인정보 처리방침과 AppGallery 개인정보 라벨에 "부정 행위 방지용 기기 식별자"를 명시하세요.
문제 해결
ohpm install이 패키지를 찾지 못함file:경로는entry모듈 기준 상대 경로입니다. 파일이entry/libs/에 있고oh-package.json5의 파일 이름과 정확히 같은지 확인하세요.업그레이드 후에도 이전 버전이 사용됨
entry/libs/에서 이전.har를 삭제하고file:경로의 버전을 바꾼 뒤ohpm install(또는 Sync Now)을 다시 실행하세요.SHA-256이 일치하지 않음
SDK 다운로드에서 HAR를 다시 내려받으세요. 대시보드 값과 일치하지 않는 파일은 배포하지 마세요.onError에서server_token_*코드가 반환됨
앱의setAction이 토큰 발급 시의action과 같은지,setOnServerTokenExpired가 새 토큰을 반환하는지 확인하세요.기기가 HarmonyOS 4.x 이하
지원하지 않습니다. 이런 기기는 Android 앱을 실행하므로 Android SDK를 사용하세요.
요구 사항
- HarmonyOS NEXT, API 12(HarmonyOS 5.0.0) 이상, Stage 모델
- 기기 유형: 휴대폰, 태블릿, 2-in-1
- ABI:
arm64-v8a,x86_64(에뮬레이터) ohos.permission.INTERNET