HarmonyOS SDK
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 và nhật ký thay đổi.
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.
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ộ.
- Đăng nhập bảng điều khiển và mở Tải SDK. Trang này cũng cung cấp dự án demo HarmonyOS (mã nguồn) để mở trong DevEco Studio.
- Tải HAR cho HarmonyOS, ví dụ
captchala-1.2.0.har. - 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 đó.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Sao chép tệp vào
entry/libs/và thêm vàoentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Chạy
ohpm installtrong thư mụcentry, hoặc nhấn Sync Now trong DevEco Studio.
cd entry
ohpm installHAR 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:
// 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ý:
- Backend của bạn cấp một
server_tokendùng một lần cho người dùng đã đăng nhập (xem Server token). - Ứng dụng truyền token đó cho SDK và mở CAPTCHA.
onSuccesstrả vềpassToken; ứng dụng gửi nó lên backend của bạn.- Backend của bạn xác thực
passToken(xem Xác thực phía máy chủ).
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 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 đó:
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{
"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, hoặc dùng SDK máy chủ PHP / Go.
API chính
| 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) 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). |
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 singletonCấu hình
| 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<string | null> 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ư). |
setLoadingStyle(string) | 'spinner' | Chỉ báo đang tải, xem Chỉ báo đang tải. |
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
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().
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
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()đếnonReady.setLoadingColor:#RRGGBBhoặc#RRGGBBAA, mặc định màu trắng.setLoadingSize:'small','medium'(mặc định) hoặc'large'.setLoadingDelay: mili giây,0–5000.
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ủ
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.
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" }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.
Quyền riêng tư
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:
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ố
ohpm installkhông tìm thấy gói
Đường dẫnfile:là tương đối so với moduleentry. Kiểm tra tệp nằm trongentry/libs/và tên tệp khớp chính xác với tên trongoh-package.json5.Sau khi nâng cấp vẫn dùng phiên bản cũ
Xóa tệp.harcũ khỏientry/libs/, cập nhật phiên bản trong đường dẫnfile:, rồi chạy lạiohpm install(hoặc Sync Now).SHA-256 không khớp
Tải lại HAR từ Tải SDK. 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.onErrortrả về mãserver_token_*
Kiểm trasetActioncủa ứng dụng có khớp vớiactiondùng khi cấp token không, vàsetOnServerTokenExpiredcó 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.
Yêu cầu
- 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