--- title: HarmonyOS SDK description: "SDK CaptchaLa cho HarmonyOS NEXT (ArkTS): cài đặt HAR từ bảng điều khiển, luồng xác minh và xác thực phía máy chủ." --- # HarmonyOS SDK ::: info SDK 1.2.0 Đã cập nhật cho SDK 1.2.0. Một số chi tiết chỉ có bằng tiếng Anh: xem [trang tiếng Anh](/sdk/harmony) và [nhật ký thay đổi](/changelog#sdk-1-2-0). ::: SDK ArkTS cho **HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 trở lên)**, phân phối dưới dạng một tệp `.har` duy nhất (`@captchala/captchala`). Phiên bản hiện tại: **1.2.0**. Luồng xác minh giống với SDK Android và iOS: thử thách mở trong một hộp thoại phía trên trang của bạn, và backend của bạn xác thực `passToken` được trả về. ::: info HarmonyOS 4.x trở về trước chạy ứng dụng Android. Trên các thiết bị đó, hãy dùng [Android SDK](./android). ::: ## Cài đặt SDK **không được phát hành trên ohpm**. Bạn tải HAR từ bảng điều khiển rồi thêm làm phụ thuộc cục bộ. 1. Đăng nhập bảng điều khiển và mở [**Tải SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Trang này cũng cung cấp dự án demo HarmonyOS (mã nguồn) để mở trong DevEco Studio. 2. Tải HAR cho HarmonyOS, ví dụ `captchala-1.2.0.har`. 3. So sánh SHA-256 của tệp với giá trị hiển thị trên trang tải xuống. Nếu khác nhau, đừng sử dụng tệp đó. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Sao chép tệp vào `entry/libs/` và thêm vào `entry/oh-package.json5`: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. Chạy `ohpm install` trong thư mục `entry`, hoặc nhấn **Sync Now** trong DevEco Studio. ```bash cd entry ohpm install ``` HAR là bản build release đã được làm rối mã, chỉ công khai API được liệt kê bên dưới. Quy tắc làm rối cho phía sử dụng đã đi kèm trong HAR, nên bản build release của bạn không cần thêm quy tắc keep nào. ### Quyền SDK chỉ dùng một quyền là `ohos.permission.INTERNET`. SDK không bao giờ yêu cầu hay hiển thị hộp thoại xin quyền lúc chạy. Hãy đảm bảo module entry của bạn đã khai báo quyền này: ```json5 // entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } } ``` ### Nâng cấp Tải HAR mới, sao chép vào `entry/libs/`, sửa phiên bản trong đường dẫn `file:` của `entry/oh-package.json5`, xóa tệp `.har` cũ rồi chạy lại `ohpm install`. ## Bắt đầu nhanh Luồng xử lý: 1. Backend của bạn cấp một `server_token` dùng một lần cho người dùng đã đăng nhập (xem [Server token](#server-token)). 2. Ứng dụng truyền token đó cho SDK và mở CAPTCHA. 3. `onSuccess` trả về `passToken`; ứng dụng gửi nó lên backend của bạn. 4. Backend của bạn xác thực `passToken` (xem [Xác thực phía máy chủ](#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` do backend của bạn tạo, không phải ứng dụng: backend gọi `/v1/server/challenge/issue` với `X-App-Key` + `X-App-Secret`. Truyền `bind_uid` là ID người dùng trong hệ thống của bạn để token, và `passToken` sinh ra từ nó, thuộc về người dùng đó: ```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 } } ``` Trả `data.server_token` (tiền tố `sct_`) về cho ứng dụng. `action` phải khớp với giá trị truyền vào `setAction`. Khi đặt `setOnServerTokenExpired`, SDK tự lấy token mới và thử lại nếu token bị từ chối giữa chừng; trả về `null` để nhận lỗi gốc. Các tùy chọn ràng buộc danh tính (`bind_uid`, `bind_ip`) chỉ được đặt trên máy chủ của bạn khi cấp token. Ứng dụng không bao giờ gửi chúng. Xem toàn bộ tham số trong [Tài liệu API](../api-reference#server-token), hoặc dùng SDK máy chủ [PHP](./server-php) / [Go](./server-go). ## API chính {#api-surface} | Ký hiệu | Mục đích | | --- | --- | | `CaptchalaClient.getClient(uiContext)` | Điểm vào singleton, gắn với `UIContext` của trang. | | `CaptchalaConfigBuilder` | Builder dạng chuỗi cho cấu hình (xem bảng bên dưới). `build()` trả về `CaptchalaConfig`. | | `init(config)` | Áp dụng cấu hình. Trả về client nên có thể gọi nối tiếp. | | `setListener(listener)` | Đăng ký `CaptchalaListener`. Chỉ `onSuccess` là bắt buộc; `onReady`, `onFail`, `onError`, `onClose` và `onExpired` (xem [Token hết hạn](#token-expiry)) là tùy chọn. | | `verify()` | Mở hộp thoại CAPTCHA. Kết quả được trả qua listener. | | `refresh()` / `cancel()` / `dismiss()` | Tải lại thử thách hiện tại / dừng luồng và đóng hộp thoại / đóng hộp thoại. | | `CaptchalaClient.destroy()` | Giải phóng singleton. | | `CaptchalaResult` | `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Gửi `passToken` lên backend của bạn. `ttl` không còn được khuyến nghị từ 1.2.0: máy chủ quyết định thời hạn của token và có thể thay đổi; hãy dùng `onExpired`. | | `CaptchalaError` | `code`, `message`, `detail`. Được truyền cho `onFail` (người dùng có thể thử lại) và `onError` (lỗi mạng, cấu hình hoặc hệ thống). | ```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 ``` ### Cấu hình {#configuration} | Phương thức | Mặc định | Ý nghĩa | | --- | --- | --- | | `setAppKey(string)` | bắt buộc | App Key của bạn trên bảng điều khiển. | | `setAction(string)` | `default` | Hành động nghiệp vụ (`login`, `register`, `pay`, …). Phải khớp với action của `server_token`. | | `setLang(string)` | `''` (auto) | Ngôn ngữ thử thách, ví dụ `en`, `zh-CN`. | | `setTheme(string)` | `auto` | `auto` (theo hệ thống), `light` hoặc `dark`. | | `setServerToken(string \| null)` | `null` | `server_token` do backend của bạn cấp. | | `setOnServerTokenExpired(cb)` | `null` | `() => Promise` lấy `server_token` mới từ backend của bạn. | | `setTimeout(number)` | `10000` | Thời gian chờ yêu cầu, ms. | | `setEnableVoice(boolean)` | `true` | Cung cấp thử thách bằng âm thanh. | | `setEnableOfflineMode(boolean)` | `false` | Cho phép đường dự phòng khi sự cố. Kết quả mang `isOffline` / `isClientOnly`. | | `setMaskClosable(boolean)` | `false` | Chạm vào nền sẽ đóng hộp thoại. | | `setCollectOdid(boolean)` | `true` | Gửi giá trị băm của ODID thiết bị (xem [Quyền riêng tư](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Chỉ báo đang tải, xem [Chỉ báo đang tải](#loading-indicator). | | `setLoadingColor(string \| null)` | trắng | Màu chỉ báo, `#RRGGBB` hoặc `#RRGGBBAA`. | | `setLoadingSize(string)` | `'medium'` | `'small'`, `'medium'` hoặc `'large'`. | | `setLoadingDelay(number)` | `300` | Số mili giây trước khi chỉ báo xuất hiện, `0`–`5000`. | | `setDebug(boolean)` | `false` | Ghi log chi tiết khi phát triển. | ## Token hết hạn {#token-expiry} Pass token nhận từ `onSuccess` chỉ có hiệu lực trong một khoảng thời gian do máy chủ quyết định. Nếu trang của bạn chưa dùng nó trước khi hết hạn, `onExpired(passToken)` của listener được gọi một lần, để bạn xóa token đã lưu và yêu cầu người dùng xác minh lại thay vì gửi một token đã hết hạn. Bắt đầu lượt xác minh mới bằng `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` không được gọi sau một lần `verify()`, `init()` hoặc `destroy()` mới. Có từ 1.2.0. ## Chỉ báo đang tải {#loading-indicator} Trong khi thử thách đang tải, SDK hiển thị một chỉ báo nhỏ trên lớp nền mờ. Chỉ báo chỉ xuất hiện khi việc tải lâu hơn `setLoadingDelay` và biến mất khi thử thách được hiển thị. Có từ 1.2.0. - `setLoadingStyle`: `'spinner'` (mặc định, dạng nan), `'ring'` (cung tròn xoay), `'dots'` hoặc `'none'`. Với `'none'` không có gì được hiển thị: hãy hiển thị chỉ báo của riêng bạn từ `verify()` đến `onReady`. - `setLoadingColor`: `#RRGGBB` hoặc `#RRGGBBAA`, mặc định màu trắng. - `setLoadingSize`: `'small'`, `'medium'` (mặc định) hoặc `'large'`. - `setLoadingDelay`: mili giây, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Xác thực phía máy chủ {#server-side-validation} Chuyển `result.passToken` lên backend và xác thực với API CaptchaLa. Tuyệt đối không đặt `X-App-Secret` trong ứng dụng. ```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" } ``` Chỉ chấp nhận yêu cầu khi `data.valid` là `true` và `data.uid` trùng với người dùng mà bạn đã cấp `server_token`. Token chỉ dùng được một lần. Xem phản hồi đầy đủ và mã lỗi trong [Tài liệu API](../api-reference). ## Quyền riêng tư {#privacy} SDK đọc một tập thuộc tính thiết bị không cần quyền (kiểu máy, phiên bản hệ điều hành, màn hình, ngôn ngữ, múi giờ và tương tự) và chỉ dùng chúng cho việc xác minh và chống gian lận. Mặc định SDK cũng gửi giá trị băm SHA-256 đã cắt ngắn của ODID thiết bị, không bao giờ gửi giá trị gốc. Không thu thập OAID, UDID, số sê-ri hay dữ liệu tài khoản. Để tắt giá trị băm ODID: ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setCollectOdid(false) // the ODID is never read .build(); ``` Nếu giữ bật, hãy khai báo một mã định danh thiết bị dùng để chống gian lận trong chính sách quyền riêng tư và nhãn quyền riêng tư trên AppGallery. ## Khắc phục sự cố {#troubleshooting} - **`ohpm install` không tìm thấy gói** Đường dẫn `file:` là tương đối so với module `entry`. Kiểm tra tệp nằm trong `entry/libs/` và tên tệp khớp chính xác với tên trong `oh-package.json5`. - **Sau khi nâng cấp vẫn dùng phiên bản cũ** Xóa tệp `.har` cũ khỏi `entry/libs/`, cập nhật phiên bản trong đường dẫn `file:`, rồi chạy lại `ohpm install` (hoặc **Sync Now**). - **SHA-256 không khớp** Tải lại HAR từ [**Tải SDK**](https://dash.captcha.la/sdk-downloads?platform=harmony). Không phát hành tệp có mã kiểm tra khác với giá trị trên bảng điều khiển. - **`onError` trả về mã `server_token_*`** Kiểm tra `setAction` của ứng dụng có khớp với `action` dùng khi cấp token không, và `setOnServerTokenExpired` có trả về token mới không. - **Thiết bị chạy HarmonyOS 4.x trở về trước** Không được hỗ trợ. Các thiết bị này chạy ứng dụng Android; hãy dùng [Android SDK](./android). ## Yêu cầu {#requirements} - HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) trở lên, mô hình Stage - Loại thiết bị: điện thoại, máy tính bảng, 2 trong 1 - ABI: `arm64-v8a`, `x86_64` (trình giả lập) - `ohos.permission.INTERNET`