Skip to content

HarmonyOS SDK ​

SDK 1.2.0

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를 사용하세요.

설치 ​

SDK는 ohpm에 게시되어 있지 않습니다. 대시보드에서 HAR를 내려받아 로컬 의존성으로 추가합니다.

  1. 대시보드에 로그인하고 SDK 다운로드를 엽니다. 같은 페이지에서 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
  1. 파일을 entry/libs/에 복사하고 entry/oh-package.json5에 추가합니다.
json5
// entry/oh-package.json5
{
  "dependencies": {
    "@captchala/captchala": "file:./libs/captchala-1.2.0.har"
  }
}
  1. 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 참고).
  2. 앱이 이를 SDK에 전달하고 CAPTCHA를 엽니다.
  3. onSuccess가 passToken을 반환하면 앱이 이를 백엔드로 보냅니다.
  4. 백엔드가 passToken을 검증합니다(서버 측 검증 참고).
ts
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이 해당 사용자에게 귀속됩니다.

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 레퍼런스를 참고하거나 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()싱글턴을 해제합니다.
CaptchalaResultpassToken, challengeId, ttl, isOffline, isClientOnly. passToken을 백엔드로 보냅니다. ttl은 1.2.0부터 사용 중단되었습니다. 토큰 수명은 서버가 정하며 바뀔 수 있으므로 onExpired를 사용하세요.
CaptchalaErrorcode, 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

설정 ​

메서드기본값설명
setAppKey(string)필수대시보드의 App Key.
setAction(string)default비즈니스 액션(login, register, pay 등). server_token의 action과 같아야 합니다.
setLang(string)'' (auto)챌린지 언어(예: en, zh-CN).
setTheme(string)autoauto(시스템을 따름), 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()로 시작합니다.

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부터 사용할 수 있습니다.

로딩 표시기 ​

챌린지를 불러오는 동안 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();

서버 측 검증 ​

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": "<result.passToken>", "expected_action": "login" }

data.valid가 true이고 data.uid가 server_token을 발급한 사용자와 같을 때만 요청을 허용합니다. 토큰은 한 번만 사용할 수 있습니다. 전체 응답과 오류 코드는 API 레퍼런스를 참고하세요.

개인정보 ​

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 개인정보 라벨에 "부정 행위 방지용 기기 식별자"를 명시하세요.

문제 해결 ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently