Skip to content

HarmonyOS SDK ​

SDK 1.2.0

Dikemas kini untuk SDK 1.2.0. Sesetengah butiran hanya tersedia dalam bahasa Inggeris: lihat halaman bahasa Inggeris dan log perubahan.

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.

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. 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
  1. 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"
  }
}
  1. 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).
  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).
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 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, atau gunakan SDK pelayan PHP / Go.

API utama ​

SimbolTujuan
CaptchalaClient.getClient(uiContext)Titik masuk singleton, terikat pada UIContext halaman anda.
CaptchalaConfigBuilderBuilder 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) 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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

SetterLalaiMaksud
setAppKey(string)wajibApp Key anda dari papan pemuka.
setAction(string)defaultTindakan perniagaan (login, register, pay, …). Mesti sama dengan action pada server_token.
setLang(string)'' (auto)Bahasa cabaran, contohnya en, zh-CN.
setTheme(string)autoauto (mengikut sistem), light atau dark.
setServerToken(string | null)nullserver_token yang dikeluarkan oleh backend anda.
setOnServerTokenExpired(cb)null() => Promise<string | null> yang mendapatkan server_token baharu daripada backend anda.
setTimeout(number)10000Had masa permintaan, ms.
setEnableVoice(boolean)trueMenawarkan cabaran audio.
setEnableOfflineMode(boolean)falseMembenarkan laluan sandaran semasa gangguan. Keputusannya membawa isOffline / isClientOnly.
setMaskClosable(boolean)falseMengetik latar belakang menutup dialog.
setCollectOdid(boolean)trueMenghantar cincangan ODID peranti (lihat Privasi).
setLoadingStyle(string)'spinner'Penunjuk pemuatan, lihat Penunjuk pemuatan.
setLoadingColor(string | null)putihWarna penunjuk, #RRGGBB atau #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' atau 'large'.
setLoadingDelay(number)300Milisaat sebelum penunjuk muncul, 0–5000.
setDebug(boolean)falseLog terperinci semasa pembangunan.

Tamat tempoh token ​

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 ​

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 ​

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": "<result.passToken>", "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.

Privasi ​

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 ​

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

Keperluan ​

  • 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

MIT-licensed examples · CaptchaLa is operated independently