--- title: HarmonyOS SDK description: "HarmonyOS NEXT용 CaptchaLa SDK(ArkTS): 대시보드에서 HAR 설치, 검증 흐름, 서버 측 검증." --- # HarmonyOS SDK ::: info SDK 1.2.0 SDK 1.2.0에 맞춰 업데이트되었습니다. 일부 세부 정보는 영어로만 제공됩니다. [영어 페이지](/sdk/harmony)와 [변경 내역](/changelog#sdk-1-2-0)을 참고하세요. ::: **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](./android)를 사용하세요. ::: ## 설치 SDK는 **ohpm에 게시되어 있지 않습니다**. 대시보드에서 HAR를 내려받아 로컬 의존성으로 추가합니다. 1. 대시보드에 로그인하고 [**SDK 다운로드**](https://dash.captcha.la/sdk-downloads?platform=harmony)를 엽니다. 같은 페이지에서 DevEco Studio로 열 수 있는 HarmonyOS 데모 프로젝트(소스)도 받을 수 있습니다. 2. HarmonyOS HAR(예: `captchala-1.2.0.har`)를 내려받습니다. 3. 파일의 SHA-256을 다운로드 페이지에 표시된 값과 비교합니다. 다르면 해당 파일을 사용하지 마세요. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. 파일을 `entry/libs/`에 복사하고 `entry/oh-package.json5`에 추가합니다. ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. `entry` 디렉터리에서 `ohpm install`을 실행하거나 DevEco Studio에서 **Sync Now**를 클릭합니다. ```bash cd entry ohpm install ``` HAR는 난독화된 릴리스 빌드이며 아래에 나열한 공개 API만 노출합니다. 사용 측 난독화 규칙이 HAR에 포함되어 있으므로 릴리스 빌드에 keep 규칙을 추가할 필요가 없습니다. ### 권한 SDK는 `ohos.permission.INTERNET` 권한 하나만 사용하며, 런타임 권한을 요청하거나 묻지 않습니다. entry 모듈에 선언되어 있는지 확인하세요. ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### 업그레이드 새 HAR를 내려받아 `entry/libs/`에 복사하고, `entry/oh-package.json5`의 `file:` 경로에 있는 버전을 바꾼 뒤 이전 `.har`를 삭제하고 `ohpm install`을 다시 실행합니다. ## 빠른 시작 전체 흐름: 1. 백엔드가 로그인한 사용자용 일회성 `server_token`을 발급합니다([Server token](#server-token) 참고). 2. 앱이 이를 SDK에 전달하고 CAPTCHA를 엽니다. 3. `onSuccess`가 `passToken`을 반환하면 앱이 이를 백엔드로 보냅니다. 4. 백엔드가 `passToken`을 검증합니다([서버 측 검증](#server-side-validation) 참고). ```ts import { CaptchalaClient, CaptchalaConfigBuilder, CaptchalaListener, CaptchalaResult, CaptchalaError } from '@captchala/captchala'; @Entry @Component struct Login { private async verify(): Promise { // 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} `server_token`은 앱이 아니라 백엔드가 `X-App-Key` + `X-App-Secret`으로 `/v1/server/challenge/issue`를 호출해 발급합니다. 자체 사용자 ID를 `bind_uid`로 전달하면 토큰과 그로부터 나온 `passToken`이 해당 사용자에게 귀속됩니다. ```bash 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 ``` ```json { "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 레퍼런스](../api-reference#server-token)를 참고하거나 [PHP](./server-php) / [Go](./server-go) 서버 SDK를 사용하세요. ## 주요 API {#api-surface} | 심볼 | 용도 | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | 싱글턴 진입점으로, 페이지의 `UIContext`에 연결됩니다. | | `CaptchalaConfigBuilder` | 설정용 빌더(아래 표 참고). `build()`는 `CaptchalaConfig`를 반환합니다. | | `init(config)` | 설정을 적용합니다. client를 반환하므로 체이닝할 수 있습니다. | | `setListener(listener)` | `CaptchalaListener`를 등록합니다. `onSuccess`만 필수이며 `onReady`, `onFail`, `onError`, `onClose`, `onExpired`([토큰 만료](#token-expiry) 참고)는 선택입니다. | | `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`(네트워크·설정·시스템 오류)에 전달됩니다. | ```ts 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 ``` ### 설정 {#configuration} | 메서드 | 기본값 | 설명 | | --- | --- | --- | | `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`. | | `setTimeout(number)` | `10000` | 요청 타임아웃(ms). | | `setEnableVoice(boolean)` | `true` | 음성 챌린지를 제공합니다. | | `setEnableOfflineMode(boolean)` | `false` | 장애 시 대체 경로를 허용합니다. 결과에 `isOffline` / `isClientOnly`가 표시됩니다. | | `setMaskClosable(boolean)` | `false` | 배경을 탭하면 대화상자가 닫힙니다. | | `setCollectOdid(boolean)` | `true` | 기기 ODID의 해시를 전송합니다([개인정보](#privacy) 참고). | | `setLoadingStyle(string)` | `'spinner'` | 로딩 표시기. [로딩 표시기](#loading-indicator) 참고. | | `setLoadingColor(string \| null)` | 흰색 | 표시기 색상, `#RRGGBB` 또는 `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` 또는 `'large'`. | | `setLoadingDelay(number)` | `300` | 표시기가 나타나기 전까지의 밀리초, `0`–`5000`. | | `setDebug(boolean)` | `false` | 개발 중 상세 로그. | ## 토큰 만료 {#token-expiry} `onSuccess`로 받은 pass token은 서버가 정한 시간 동안만 유효합니다. 그때까지 페이지에서 사용하지 않으면 listener의 `onExpired(passToken)`이 한 번 호출됩니다. 저장해 둔 토큰을 지우고, 만료된 토큰을 제출하는 대신 사용자에게 다시 인증하도록 안내하세요. 새 인증은 `verify()`로 시작합니다. ```ts 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부터 사용할 수 있습니다. ## 로딩 표시기 {#loading-indicator} 챌린지를 불러오는 동안 SDK는 어둡게 처리된 배경 위에 작은 표시기를 보여 줍니다. 로딩이 `setLoadingDelay`보다 오래 걸릴 때만 나타나며 챌린지가 표시되면 사라집니다. 1.2.0부터 사용할 수 있습니다. - `setLoadingStyle`: `'spinner'`(기본값, 살), `'ring'`(회전하는 호), `'dots'` 또는 `'none'`. `'none'`이면 아무것도 표시하지 않으므로 `verify()`부터 `onReady`까지 직접 만든 표시기를 보여 주세요. - `setLoadingColor`: `#RRGGBB` 또는 `#RRGGBBAA`, 기본값은 흰색. - `setLoadingSize`: `'small'`, `'medium'`(기본값) 또는 `'large'`. - `setLoadingDelay`: 밀리초, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## 서버 측 검증 {#server-side-validation} `result.passToken`을 백엔드로 전달해 CaptchaLa API로 검증합니다. `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": "", "expected_action": "login" } ``` `data.valid`가 `true`이고 `data.uid`가 `server_token`을 발급한 사용자와 같을 때만 요청을 허용합니다. 토큰은 한 번만 사용할 수 있습니다. 전체 응답과 오류 코드는 [API 레퍼런스](../api-reference)를 참고하세요. ## 개인정보 {#privacy} SDK는 권한이 필요 없는 기기 속성(모델, OS 버전, 화면, 로캘, 시간대 등)을 읽어 검증과 부정 행위 방지에만 사용합니다. 기본적으로 기기 ODID의 SHA-256 해시(잘라낸 값)도 전송하며 원본 값은 보내지 않습니다. OAID, UDID, 일련번호, 계정 데이터는 수집하지 않습니다. ODID 해시를 끄려면: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` 켜 둔다면 개인정보 처리방침과 AppGallery 개인정보 라벨에 "부정 행위 방지용 기기 식별자"를 명시하세요. ## 문제 해결 {#troubleshooting} - **`ohpm install`이 패키지를 찾지 못함** `file:` 경로는 `entry` 모듈 기준 상대 경로입니다. 파일이 `entry/libs/`에 있고 `oh-package.json5`의 파일 이름과 정확히 같은지 확인하세요. - **업그레이드 후에도 이전 버전이 사용됨** `entry/libs/`에서 이전 `.har`를 삭제하고 `file:` 경로의 버전을 바꾼 뒤 `ohpm install`(또는 **Sync Now**)을 다시 실행하세요. - **SHA-256이 일치하지 않음** [**SDK 다운로드**](https://dash.captcha.la/sdk-downloads?platform=harmony)에서 HAR를 다시 내려받으세요. 대시보드 값과 일치하지 않는 파일은 배포하지 마세요. - **`onError`에서 `server_token_*` 코드가 반환됨** 앱의 `setAction`이 토큰 발급 시의 `action`과 같은지, `setOnServerTokenExpired`가 새 토큰을 반환하는지 확인하세요. - **기기가 HarmonyOS 4.x 이하** 지원하지 않습니다. 이런 기기는 Android 앱을 실행하므로 [Android SDK](./android)를 사용하세요. ## 요구 사항 {#requirements} - HarmonyOS NEXT, API 12(HarmonyOS 5.0.0) 이상, Stage 모델 - 기기 유형: 휴대폰, 태블릿, 2-in-1 - ABI: `arm64-v8a`, `x86_64`(에뮬레이터) - `ohos.permission.INTERNET`