--- title: HarmonyOS SDK description: "SDK CaptchaLa untuk HarmonyOS NEXT (ArkTS): instalasi HAR dari dasbor, alur verifikasi, dan validasi sisi server." --- # HarmonyOS SDK ::: info SDK 1.2.0 Diperbarui untuk SDK 1.2.0. Beberapa detail hanya tersedia dalam bahasa Inggris: lihat [halaman bahasa Inggris](/sdk/harmony) dan [catatan perubahan](/changelog#sdk-1-2-0). ::: SDK ArkTS untuk **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 ke atas)**, didistribusikan sebagai satu file `.har` (`@captchala/captchala`). Versi saat ini: **1.2.0**. Alur verifikasinya sama dengan SDK Android dan iOS: tantangan terbuka dalam dialog di atas halaman Anda, lalu backend Anda memvalidasi `passToken` yang dikembalikan. ::: info HarmonyOS 4.x dan versi sebelumnya menjalankan aplikasi Android. Di perangkat tersebut, gunakan [Android SDK](./android). ::: ## Instalasi SDK **tidak diterbitkan di ohpm**. Unduh HAR dari dasbor lalu tambahkan sebagai dependensi lokal. 1. Masuk ke dasbor dan buka [**Unduh SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Halaman yang sama juga menyediakan proyek demo HarmonyOS (sumber) yang bisa dibuka di DevEco Studio. 2. Unduh HAR HarmonyOS, misalnya `captchala-1.2.0.har`. 3. Bandingkan SHA-256 file dengan nilai yang ditampilkan di halaman unduhan. Jika berbeda, jangan gunakan file tersebut. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Salin file ke `entry/libs/` dan tambahkan ke `entry/oh-package.json5`: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Jalankan `ohpm install` di direktori `entry`, atau klik **Sync Now** di DevEco Studio. ```bash cd entry ohpm install ``` HAR ini adalah build release yang diobfuskasi dan hanya mengekspos API publik yang tercantum di bawah. Aturan obfuskasi untuk konsumen sudah disertakan di dalam HAR, jadi build release Anda tidak memerlukan aturan keep tambahan. ### Izin SDK hanya menggunakan satu izin, `ohos.permission.INTERNET`. SDK tidak pernah meminta atau menampilkan permintaan izin saat runtime. Pastikan modul entry Anda mendeklarasikannya: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Pembaruan Unduh HAR baru, salin ke `entry/libs/`, ubah versi di jalur `file:` pada `entry/oh-package.json5`, hapus `.har` lama, lalu jalankan `ohpm install` lagi. ## Mulai cepat Alurnya: 1. Backend Anda menerbitkan `server_token` sekali pakai untuk pengguna yang sedang masuk (lihat [Server token](#server-token)). 2. Aplikasi meneruskannya ke SDK dan membuka CAPTCHA. 3. `onSuccess` mengembalikan `passToken`; aplikasi mengirimkannya ke backend Anda. 4. Backend Anda memvalidasi `passToken` (lihat [Validasi sisi server](#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` dibuat oleh backend Anda, bukan oleh aplikasi, dengan memanggil `/v1/server/challenge/issue` menggunakan `X-App-Key` + `X-App-Secret`. Kirim `bind_uid` berisi ID pengguna di sistem Anda agar token, beserta `passToken` yang dihasilkan darinya, menjadi milik pengguna tersebut: ```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 } } ``` Kembalikan `data.server_token` (awalan `sct_`) ke aplikasi. `action` harus sama dengan nilai yang diberikan ke `setAction`. Dengan `setOnServerTokenExpired`, SDK otomatis mengambil token baru dan mencoba lagi saat token ditolak di tengah tantangan; kembalikan `null` untuk menerima error aslinya. Opsi pengikatan identitas (`bind_uid`, `bind_ip`) hanya diatur di server Anda saat token diterbitkan. Aplikasi tidak pernah mengirimkannya. Lihat semua parameter di [Referensi API](../api-reference#server-token), atau gunakan SDK server [PHP](./server-php) / [Go](./server-go). ## API utama {#api-surface} | Simbol | Fungsi | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Titik masuk singleton, terikat ke `UIContext` halaman Anda. | | `CaptchalaConfigBuilder` | Builder berantai untuk konfigurasi (lihat tabel di bawah). `build()` mengembalikan `CaptchalaConfig`. | | `init(config)` | Menerapkan konfigurasi. Mengembalikan client sehingga pemanggilan bisa dirangkai. | | `setListener(listener)` | Mendaftarkan `CaptchalaListener`. Hanya `onSuccess` yang wajib; `onReady`, `onFail`, `onError`, `onClose`, dan `onExpired` (lihat [Kedaluwarsa token](#token-expiry)) opsional. | | `verify()` | Membuka dialog CAPTCHA. Hasil dikirim melalui listener. | | `refresh()` / `cancel()` / `dismiss()` | Memuat ulang tantangan saat ini / menghentikan alur dan menutup dialog / menutup dialog. | | `CaptchalaClient.destroy()` | Melepas singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Kirim `passToken` ke backend Anda. `ttl` usang sejak 1.2.0: server menentukan masa berlaku token dan dapat mengubahnya; gunakan `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Diteruskan ke `onFail` (pengguna dapat mencoba lagi) dan `onError` (error jaringan, konfigurasi, atau sistem). | ```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 ``` ### Konfigurasi {#configuration} | Setter | Default | Arti | | --- | --- | --- | | `setAppKey(string)` | wajib | App Key Anda dari dasbor. | | `setAction(string)` | `default` | Aksi bisnis (`login`, `register`, `pay`, …). Harus sama dengan action pada `server_token`. | | `setLang(string)` | `''` (auto) | Bahasa tantangan, misalnya `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (mengikuti sistem), `light`, atau `dark`. | | `setServerToken(string \| null)` | `null` | `server_token` yang diterbitkan backend Anda. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise` yang mengambil `server_token` baru dari backend Anda. | | `setTimeout(number)` | `10000` | Batas waktu permintaan, ms. | | `setEnableVoice(boolean)` | `true` | Menyediakan tantangan audio. | | `setEnableOfflineMode(boolean)` | `false` | Mengizinkan jalur cadangan saat gangguan. Hasilnya membawa `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Mengetuk latar belakang menutup dialog. | | `setCollectOdid(boolean)` | `true` | Mengirim hash ODID perangkat (lihat [Privasi](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Indikator pemuatan, lihat [Indikator pemuatan](#loading-indicator). | | `setLoadingColor(string \| null)` | putih | Warna indikator, `#RRGGBB` atau `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'`, atau `'large'`. | | `setLoadingDelay(number)` | `300` | Milidetik sebelum indikator muncul, `0`–`5000`. | | `setDebug(boolean)` | `false` | Log terperinci selama pengembangan. | ## Kedaluwarsa token {#token-expiry} Pass token dari `onSuccess` berlaku untuk waktu terbatas yang ditentukan oleh server. Jika halaman Anda belum memakainya sampai saat itu, `onExpired(passToken)` pada listener dipanggil satu kali, sehingga Anda dapat menghapus token yang tersimpan dan meminta pengguna memverifikasi ulang alih-alih mengirim token yang sudah kedaluwarsa. Mulai verifikasi baru dengan `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 } }; ``` `onExpired` tidak dipanggil setelah `verify()`, `init()`, atau `destroy()` yang baru. Tersedia sejak 1.2.0. ## Indikator pemuatan {#loading-indicator} Selama tantangan dimuat, SDK menampilkan indikator kecil di atas lapisan peredup. Indikator hanya muncul jika pemuatan berlangsung lebih lama dari `setLoadingDelay` (default 300 ms), dan hilang begitu tantangan ditampilkan. Tersedia sejak 1.2.0. - `setLoadingStyle`: `'spinner'` (default, jari-jari), `'ring'` (busur berputar), `'dots'`, atau `'none'`. Dengan `'none'` tidak ada yang ditampilkan: tampilkan indikator Anda sendiri dari `verify()` hingga `onReady`. - `setLoadingColor`: `#RRGGBB` atau `#RRGGBBAA`, default putih. - `setLoadingSize`: `'small'`, `'medium'` (default), atau `'large'`. - `setLoadingDelay`: milidetik, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Validasi sisi server {#server-side-validation} Teruskan `result.passToken` ke backend Anda dan validasi dengan API CaptchaLa. Jangan pernah menaruh `X-App-Secret` di aplikasi. ```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" } ``` Terima permintaan hanya jika `data.valid` bernilai `true` dan `data.uid` sama dengan pengguna yang Anda terbitkan `server_token`-nya. Token hanya bisa dipakai sekali. Lihat respons lengkap dan kode error di [Referensi API](../api-reference). ## Privasi {#privacy} SDK membaca sejumlah atribut perangkat yang tidak memerlukan izin (model, versi OS, layar, lokal, zona waktu, dan sejenisnya) dan hanya menggunakannya untuk verifikasi dan pencegahan penipuan. Secara default SDK juga mengirim hash SHA-256 terpotong dari ODID perangkat, tidak pernah nilai aslinya. OAID, UDID, nomor seri, atau data akun tidak dikumpulkan. Untuk mematikan hash ODID: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Jika tetap diaktifkan, nyatakan pengenal perangkat yang digunakan untuk pencegahan penipuan dalam kebijakan privasi dan label privasi AppGallery Anda. ## Pemecahan masalah {#troubleshooting} - **`ohpm install` tidak menemukan paket** Jalur `file:` bersifat relatif terhadap modul `entry`. Pastikan file ada di `entry/libs/` dan namanya sama persis dengan yang ada di `oh-package.json5`. - **Versi lama masih dipakai setelah pembaruan** Hapus `.har` lama dari `entry/libs/`, perbarui versi di jalur `file:`, lalu jalankan `ohpm install` (atau **Sync Now**) lagi. - **SHA-256 tidak cocok** Unduh ulang HAR dari [**Unduh SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Jangan rilis file yang checksum-nya tidak cocok dengan dasbor. - **`onError` dengan kode `server_token_*`** Periksa apakah `setAction` di aplikasi sama dengan `action` yang dipakai saat menerbitkan token, dan apakah `setOnServerTokenExpired` mengembalikan token baru. - **Perangkat menjalankan HarmonyOS 4.x atau sebelumnya** Tidak didukung. Perangkat ini menjalankan aplikasi Android; gunakan [Android SDK](./android). ## Persyaratan {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) ke atas, model Stage - Jenis perangkat: ponsel, tablet, 2-in-1 - ABI: `arm64-v8a`, `x86_64` (emulator) - `ohos.permission.INTERNET`