Skip to content

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ộ.

  1. Đă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.
  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
  1. 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"
  }
}
  1. 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).
  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ủ).
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 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, hoặc dùng SDK máy chủ PHP / Go.

API chính ​

Ký hiệuMục đích
CaptchalaClient.getClient(uiContext)Điểm vào singleton, gắn với UIContext của trang.
CaptchalaConfigBuilderBuilder 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

Phương thứcMặc địnhÝ nghĩa
setAppKey(string)bắt buộcApp Key của bạn trên bảng điều khiển.
setAction(string)defaultHà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)autoauto (theo hệ thống), light hoặc dark.
setServerToken(string | null)nullserver_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)10000Thời gian chờ yêu cầu, ms.
setEnableVoice(boolean)trueCung cấp thử thách bằng âm thanh.
setEnableOfflineMode(boolean)falseCho phép đường dự phòng khi sự cố. Kết quả mang isOffline / isClientOnly.
setMaskClosable(boolean)falseChạm vào nền sẽ đóng hộp thoại.
setCollectOdid(boolean)trueGử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ắngMàu chỉ báo, #RRGGBB hoặc #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' hoặc 'large'.
setLoadingDelay(number)300Số mili giây trước khi chỉ báo xuất hiện, 0–5000.
setDebug(boolean)falseGhi 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().

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 ​

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ủ ​

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": "<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:

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ố ​

  • 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. 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.

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

MIT-licensed examples · CaptchaLa is operated independently