Skip to content

HarmonyOS SDK ​

SDK 1.2.0

Diperbarui untuk SDK 1.2.0. Beberapa detail hanya tersedia dalam bahasa Inggris: lihat halaman bahasa Inggris dan catatan perubahan.

SDK ArkTS untuk HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 ke atas), didistribusikan sebagai satu file .har (@captchala/captchala). Versi saat ini: 1.2.0. Alur verifikasinya sama dengan SDK Android dan iOS: tantangan terbuka dalam dialog di atas halaman Anda, lalu backend Anda memvalidasi passToken yang dikembalikan.

INFO

HarmonyOS 4.x dan versi sebelumnya menjalankan aplikasi Android. Di perangkat tersebut, gunakan Android SDK.

Instalasi ​

SDK tidak diterbitkan di ohpm. Unduh HAR dari dasbor lalu tambahkan sebagai dependensi lokal.

  1. Masuk ke dasbor dan buka Unduh SDK. Halaman yang sama juga menyediakan proyek demo HarmonyOS (sumber) yang bisa dibuka di DevEco Studio.
  2. Unduh HAR HarmonyOS, misalnya captchala-1.2.0.har.
  3. Bandingkan SHA-256 file dengan nilai yang ditampilkan di halaman unduhan. Jika berbeda, jangan gunakan file tersebut.
bash
# macOS / Linux
shasum -a 256 captchala-1.2.0.har

# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256
  1. Salin file ke entry/libs/ dan tambahkan ke entry/oh-package.json5:
json5
// entry/oh-package.json5
{
  "dependencies": {
    "@captchala/captchala": "file:./libs/captchala-1.2.0.har"
  }
}
  1. Jalankan ohpm install di direktori entry, atau klik Sync Now di DevEco Studio.
bash
cd entry
ohpm install

HAR ini adalah build release yang diobfuskasi dan hanya mengekspos API publik yang tercantum di bawah. Aturan obfuskasi untuk konsumen sudah disertakan di dalam HAR, jadi build release Anda tidak memerlukan aturan keep tambahan.

Izin ​

SDK hanya menggunakan satu izin, ohos.permission.INTERNET. SDK tidak pernah meminta atau menampilkan permintaan izin saat runtime. Pastikan modul entry Anda mendeklarasikannya:

json5
// entry/src/main/module.json5
{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }
    ]
  }
}

Pembaruan ​

Unduh HAR baru, salin ke entry/libs/, ubah versi di jalur file: pada entry/oh-package.json5, hapus .har lama, lalu jalankan ohpm install lagi.

Mulai cepat ​

Alurnya:

  1. Backend Anda menerbitkan server_token sekali pakai untuk pengguna yang sedang masuk (lihat Server token).
  2. Aplikasi meneruskannya ke SDK dan membuka CAPTCHA.
  3. onSuccess mengembalikan passToken; aplikasi mengirimkannya ke backend Anda.
  4. Backend Anda memvalidasi passToken (lihat Validasi sisi server).
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 dibuat oleh backend Anda, bukan oleh aplikasi, dengan memanggil /v1/server/challenge/issue menggunakan X-App-Key + X-App-Secret. Kirim bind_uid berisi ID pengguna di sistem Anda agar token, beserta passToken yang dihasilkan darinya, 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_) ke aplikasi. action harus sama dengan nilai yang diberikan ke setAction. Dengan setOnServerTokenExpired, SDK otomatis mengambil token baru dan mencoba lagi saat token ditolak di tengah tantangan; kembalikan null untuk menerima error aslinya.

Opsi pengikatan identitas (bind_uid, bind_ip) hanya diatur di server Anda saat token diterbitkan. Aplikasi tidak pernah mengirimkannya. Lihat semua parameter di Referensi API, atau gunakan SDK server PHP / Go.

API utama ​

SimbolFungsi
CaptchalaClient.getClient(uiContext)Titik masuk singleton, terikat ke UIContext halaman Anda.
CaptchalaConfigBuilderBuilder berantai untuk konfigurasi (lihat tabel di bawah). build() mengembalikan CaptchalaConfig.
init(config)Menerapkan konfigurasi. Mengembalikan client sehingga pemanggilan bisa dirangkai.
setListener(listener)Mendaftarkan CaptchalaListener. Hanya onSuccess yang wajib; onReady, onFail, onError, onClose, dan onExpired (lihat Kedaluwarsa token) opsional.
verify()Membuka dialog CAPTCHA. Hasil dikirim melalui listener.
refresh() / cancel() / dismiss()Memuat ulang tantangan saat ini / menghentikan alur dan menutup dialog / menutup dialog.
CaptchalaClient.destroy()Melepas singleton.
CaptchalaResultpassToken, challengeId, ttl, isOffline, isClientOnly. Kirim passToken ke backend Anda. ttl usang sejak 1.2.0: server menentukan masa berlaku token dan dapat mengubahnya; gunakan onExpired.
CaptchalaErrorcode, message, detail. Diteruskan ke onFail (pengguna dapat mencoba lagi) dan onError (error jaringan, 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 ​

SetterDefaultArti
setAppKey(string)wajibApp Key Anda dari dasbor.
setAction(string)defaultAksi bisnis (login, register, pay, …). Harus sama dengan action pada server_token.
setLang(string)'' (auto)Bahasa tantangan, misalnya en, zh-CN.
setTheme(string)autoauto (mengikuti sistem), light, atau dark.
setServerToken(string | null)nullserver_token yang diterbitkan backend Anda.
setOnServerTokenExpired(cb)null() => Promise<string | null> yang mengambil server_token baru dari backend Anda.
setTimeout(number)10000Batas waktu permintaan, ms.
setEnableVoice(boolean)trueMenyediakan tantangan audio.
setEnableOfflineMode(boolean)falseMengizinkan jalur cadangan saat gangguan. Hasilnya membawa isOffline / isClientOnly.
setMaskClosable(boolean)falseMengetuk latar belakang menutup dialog.
setCollectOdid(boolean)trueMengirim hash ODID perangkat (lihat Privasi).
setLoadingStyle(string)'spinner'Indikator pemuatan, lihat Indikator pemuatan.
setLoadingColor(string | null)putihWarna indikator, #RRGGBB atau #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium', atau 'large'.
setLoadingDelay(number)300Milidetik sebelum indikator muncul, 0–5000.
setDebug(boolean)falseLog terperinci selama pengembangan.

Kedaluwarsa token ​

Pass token dari onSuccess berlaku untuk waktu terbatas yang ditentukan oleh server. Jika halaman Anda belum memakainya sampai saat itu, onExpired(passToken) pada listener dipanggil satu kali, sehingga Anda dapat menghapus token yang tersimpan dan meminta pengguna memverifikasi ulang alih-alih mengirim token yang sudah kedaluwarsa. Mulai verifikasi baru 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 setelah verify(), init(), atau destroy() yang baru. Tersedia sejak 1.2.0.

Indikator pemuatan ​

Selama tantangan dimuat, SDK menampilkan indikator kecil di atas lapisan peredup. Indikator hanya muncul jika pemuatan berlangsung lebih lama dari setLoadingDelay (default 300 ms), dan hilang begitu tantangan ditampilkan. Tersedia sejak 1.2.0.

  • setLoadingStyle: 'spinner' (default, jari-jari), 'ring' (busur berputar), 'dots', atau 'none'. Dengan 'none' tidak ada yang ditampilkan: tampilkan indikator Anda sendiri dari verify() hingga onReady.
  • setLoadingColor: #RRGGBB atau #RRGGBBAA, default putih.
  • setLoadingSize: 'small', 'medium' (default), atau 'large'.
  • setLoadingDelay: milidetik, 0–5000.
ts
const config = new CaptchalaConfigBuilder()
  .setAppKey('YOUR_APP_KEY')
  .setLoadingStyle('dots')
  .setLoadingColor('#3B82F6')
  .setLoadingSize('small')
  .setLoadingDelay(500)
  .build();

Validasi sisi server ​

Teruskan result.passToken ke backend Anda dan validasi dengan API CaptchaLa. Jangan pernah menaruh X-App-Secret di 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 jika data.valid bernilai true dan data.uid sama dengan pengguna yang Anda terbitkan server_token-nya. Token hanya bisa dipakai sekali. Lihat respons lengkap dan kode error di Referensi API.

Privasi ​

SDK membaca sejumlah atribut perangkat yang tidak memerlukan izin (model, versi OS, layar, lokal, zona waktu, dan sejenisnya) dan hanya menggunakannya untuk verifikasi dan pencegahan penipuan. Secara default SDK juga mengirim hash SHA-256 terpotong dari ODID perangkat, tidak pernah nilai aslinya. OAID, UDID, nomor seri, atau data akun tidak dikumpulkan. Untuk mematikan hash ODID:

ts
const config = new CaptchalaConfigBuilder()
  .setAppKey('YOUR_APP_KEY')
  .setCollectOdid(false)     // the ODID is never read
  .build();

Jika tetap diaktifkan, nyatakan pengenal perangkat yang digunakan untuk pencegahan penipuan dalam kebijakan privasi dan label privasi AppGallery Anda.

Pemecahan masalah ​

  • ohpm install tidak menemukan paket
    Jalur file: bersifat relatif terhadap modul entry. Pastikan file ada di entry/libs/ dan namanya sama persis dengan yang ada di oh-package.json5.

  • Versi lama masih dipakai setelah pembaruan
    Hapus .har lama dari entry/libs/, perbarui versi di jalur file:, lalu jalankan ohpm install (atau Sync Now) lagi.

  • SHA-256 tidak cocok
    Unduh ulang HAR dari Unduh SDK. Jangan rilis file yang checksum-nya tidak cocok dengan dasbor.

  • onError dengan kode server_token_*
    Periksa apakah setAction di aplikasi sama dengan action yang dipakai saat menerbitkan token, dan apakah setOnServerTokenExpired mengembalikan token baru.

  • Perangkat menjalankan HarmonyOS 4.x atau sebelumnya
    Tidak didukung. Perangkat ini menjalankan aplikasi Android; gunakan Android SDK.

Persyaratan ​

  • HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) ke atas, model Stage
  • Jenis perangkat: ponsel, tablet, 2-in-1
  • ABI: arm64-v8a, x86_64 (emulator)
  • ohos.permission.INTERNET

MIT-licensed examples · CaptchaLa is operated independently