--- title: HarmonyOS SDK description: "SDK CaptchaLa untuk HarmonyOS NEXT (ArkTS): pemasangan HAR dari papan pemuka, aliran pengesahan dan pengesahan di pelayan." --- # HarmonyOS SDK ::: info SDK 1.2.0 Dikemas kini untuk SDK 1.2.0. Sesetengah butiran hanya tersedia dalam bahasa Inggeris: lihat [halaman bahasa Inggeris](/sdk/harmony) dan [log perubahan](/changelog#sdk-1-2-0). ::: SDK ArkTS untuk **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 dan ke atas)**, diedarkan sebagai satu fail `.har` (`@captchala/captchala`). Versi semasa: **1.2.0**. Aliran pengesahannya sama seperti SDK Android dan iOS: cabaran dibuka dalam dialog di atas halaman anda, dan backend anda mengesahkan `passToken` yang dikembalikan. ::: info HarmonyOS 4.x dan versi lebih awal menjalankan aplikasi Android. Pada peranti tersebut, gunakan [Android SDK](./android). ::: ## Pemasangan SDK **tidak diterbitkan di ohpm**. Muat turun HAR dari papan pemuka dan tambahkannya sebagai kebergantungan setempat. 1. Log masuk ke papan pemuka dan buka [**Muat turun SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Halaman yang sama juga menyediakan projek demo HarmonyOS (sumber) yang boleh dibuka dalam DevEco Studio. 2. Muat turun HAR HarmonyOS, contohnya `captchala-1.2.0.har`. 3. Bandingkan SHA-256 fail dengan nilai yang dipaparkan di halaman muat turun. Jika berbeza, jangan gunakan fail itu. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Salin fail ke `entry/libs/` dan tambahkannya dalam `entry/oh-package.json5`: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Jalankan `ohpm install` dalam direktori `entry`, atau klik **Sync Now** dalam DevEco Studio. ```bash cd entry ohpm install ``` HAR ini ialah binaan release yang dikaburkan dan hanya mendedahkan API awam yang disenaraikan di bawah. Peraturan pengaburan untuk pengguna sudah disertakan dalam HAR, jadi binaan release anda tidak memerlukan peraturan keep tambahan. ### Kebenaran SDK hanya menggunakan satu kebenaran, `ohos.permission.INTERNET`. Ia tidak pernah meminta atau memaparkan permintaan kebenaran semasa masa jalan. Pastikan modul entry anda mengisytiharkannya: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Naik taraf Muat turun HAR baharu, salin ke `entry/libs/`, tukar versi dalam laluan `file:` di `entry/oh-package.json5`, padam `.har` lama, kemudian jalankan `ohpm install` sekali lagi. ## Mula pantas Alirannya: 1. Backend anda mengeluarkan `server_token` sekali guna untuk pengguna yang telah log masuk (lihat [Server token](#server-token)). 2. Aplikasi menghantarnya kepada SDK dan membuka CAPTCHA. 3. `onSuccess` mengembalikan `passToken`; aplikasi menghantarnya ke backend anda. 4. Backend anda mengesahkan `passToken` (lihat [Pengesahan di pelayan](#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` dijana oleh backend anda, bukan aplikasi, dengan memanggil `/v1/server/challenge/issue` menggunakan `X-App-Key` + `X-App-Secret`. Hantar `bind_uid` dengan ID pengguna dalam sistem anda supaya token, dan `passToken` yang terhasil daripadanya, 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_`) kepada aplikasi. `action` mesti sama dengan nilai yang diberikan kepada `setAction`. Dengan `setOnServerTokenExpired`, SDK akan mendapatkan token baharu dan mencuba semula sendiri apabila token ditolak di tengah cabaran; kembalikan `null` untuk menerima ralat asal. Pilihan pengikatan identiti (`bind_uid`, `bind_ip`) hanya ditetapkan pada pelayan anda semasa token dikeluarkan. Aplikasi tidak pernah menghantarnya. Lihat semua parameter dalam [Rujukan API](../api-reference#server-token), atau gunakan SDK pelayan [PHP](./server-php) / [Go](./server-go). ## API utama {#api-surface} | Simbol | Tujuan | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Titik masuk singleton, terikat pada `UIContext` halaman anda. | | `CaptchalaConfigBuilder` | Builder berantai untuk konfigurasi (lihat jadual di bawah). `build()` mengembalikan `CaptchalaConfig`. | | `init(config)` | Menggunakan konfigurasi. Mengembalikan client supaya panggilan boleh dirantai. | | `setListener(listener)` | Mendaftar `CaptchalaListener`. Hanya `onSuccess` wajib; `onReady`, `onFail`, `onError`, `onClose` dan `onExpired` (lihat [Tamat tempoh token](#token-expiry)) adalah pilihan. | | `verify()` | Membuka dialog CAPTCHA. Keputusan dihantar melalui listener. | | `refresh()` / `cancel()` / `dismiss()` | Muat semula cabaran semasa / hentikan aliran dan tutup dialog / tutup dialog. | | `CaptchalaClient.destroy()` | Melepaskan singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Hantar `passToken` ke backend anda. `ttl` tidak digunakan lagi sejak 1.2.0: pelayan menentukan hayat token dan boleh mengubahnya; gunakan `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Dihantar kepada `onFail` (pengguna boleh cuba lagi) dan `onError` (ralat rangkaian, 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 | Lalai | Maksud | | --- | --- | --- | | `setAppKey(string)` | wajib | App Key anda dari papan pemuka. | | `setAction(string)` | `default` | Tindakan perniagaan (`login`, `register`, `pay`, …). Mesti sama dengan action pada `server_token`. | | `setLang(string)` | `''` (auto) | Bahasa cabaran, contohnya `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (mengikut sistem), `light` atau `dark`. | | `setServerToken(string \| null)` | `null` | `server_token` yang dikeluarkan oleh backend anda. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise` yang mendapatkan `server_token` baharu daripada backend anda. | | `setTimeout(number)` | `10000` | Had masa permintaan, ms. | | `setEnableVoice(boolean)` | `true` | Menawarkan cabaran audio. | | `setEnableOfflineMode(boolean)` | `false` | Membenarkan laluan sandaran semasa gangguan. Keputusannya membawa `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Mengetik latar belakang menutup dialog. | | `setCollectOdid(boolean)` | `true` | Menghantar cincangan ODID peranti (lihat [Privasi](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Penunjuk pemuatan, lihat [Penunjuk pemuatan](#loading-indicator). | | `setLoadingColor(string \| null)` | putih | Warna penunjuk, `#RRGGBB` atau `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` atau `'large'`. | | `setLoadingDelay(number)` | `300` | Milisaat sebelum penunjuk muncul, `0`–`5000`. | | `setDebug(boolean)` | `false` | Log terperinci semasa pembangunan. | ## Tamat tempoh token {#token-expiry} Pass token daripada `onSuccess` sah untuk tempoh terhad yang ditentukan oleh pelayan. Jika halaman anda belum menggunakannya dalam tempoh itu, `onExpired(passToken)` pada listener dipanggil sekali, supaya anda boleh mengosongkan token yang disimpan dan meminta pengguna mengesahkan semula dan bukannya menghantar token yang telah tamat tempoh. Mulakan pengesahan baharu 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 selepas `verify()`, `init()` atau `destroy()` yang baharu. Tersedia sejak 1.2.0. ## Penunjuk pemuatan {#loading-indicator} Semasa cabaran dimuatkan, SDK memaparkan penunjuk kecil di atas latar yang dimalapkan. Ia hanya muncul jika pemuatan mengambil masa lebih lama daripada `setLoadingDelay`, dan hilang apabila cabaran dipaparkan. Tersedia sejak 1.2.0. - `setLoadingStyle`: `'spinner'` (lalai, jejari), `'ring'` (lengkok berputar), `'dots'` atau `'none'`. Dengan `'none'` tiada apa yang dipaparkan: paparkan penunjuk anda sendiri dari `verify()` hingga `onReady`. - `setLoadingColor`: `#RRGGBB` atau `#RRGGBBAA`, lalai putih. - `setLoadingSize`: `'small'`, `'medium'` (lalai) atau `'large'`. - `setLoadingDelay`: milisaat, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Pengesahan di pelayan {#server-side-validation} Majukan `result.passToken` ke backend anda dan sahkannya dengan API CaptchaLa. Jangan sekali-kali letakkan `X-App-Secret` dalam 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 apabila `data.valid` ialah `true` dan `data.uid` sama dengan pengguna yang anda keluarkan `server_token` untuknya. Token hanya boleh digunakan sekali. Lihat respons penuh dan kod ralat dalam [Rujukan API](../api-reference). ## Privasi {#privacy} SDK membaca satu set atribut peranti yang tidak memerlukan kebenaran (model, versi OS, skrin, tempatan, zon waktu dan seumpamanya) dan menggunakannya hanya untuk pengesahan dan pencegahan penipuan. Secara lalai ia juga menghantar cincangan SHA-256 terpangkas bagi ODID peranti, tidak pernah nilai mentahnya. OAID, UDID, nombor siri atau data akaun tidak dikumpul. Untuk mematikan cincangan ODID: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Jika anda mengekalkannya, isytiharkan pengecam peranti yang digunakan untuk pencegahan penipuan dalam dasar privasi dan label privasi AppGallery anda. ## Penyelesaian masalah {#troubleshooting} - **`ohpm install` tidak menemui pakej** Laluan `file:` adalah relatif kepada modul `entry`. Pastikan fail berada dalam `entry/libs/` dan namanya sama tepat dengan yang dalam `oh-package.json5`. - **Versi lama masih digunakan selepas naik taraf** Padam `.har` lama dari `entry/libs/`, kemas kini versi dalam laluan `file:`, kemudian jalankan `ohpm install` (atau **Sync Now**) sekali lagi. - **SHA-256 tidak sepadan** Muat turun semula HAR dari [**Muat turun SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Jangan keluarkan fail yang checksum-nya tidak sepadan dengan papan pemuka. - **`onError` dengan kod `server_token_*`** Semak sama ada `setAction` dalam aplikasi sama dengan `action` yang digunakan semasa mengeluarkan token, dan sama ada `setOnServerTokenExpired` mengembalikan token baharu. - **Peranti menjalankan HarmonyOS 4.x atau lebih awal** Tidak disokong. Peranti ini menjalankan aplikasi Android; gunakan [Android SDK](./android). ## Keperluan {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) dan ke atas, model Stage - Jenis peranti: telefon, tablet, 2-dalam-1 - ABI: `arm64-v8a`, `x86_64` (emulator) - `ohos.permission.INTERNET`