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.
- Masuk ke dasbor dan buka Unduh SDK. Halaman yang sama juga menyediakan proyek demo HarmonyOS (sumber) yang bisa dibuka di DevEco Studio.
- Unduh HAR HarmonyOS, misalnya
captchala-1.2.0.har. - Bandingkan SHA-256 file dengan nilai yang ditampilkan di halaman unduhan. Jika berbeda, jangan gunakan file tersebut.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Salin file ke
entry/libs/dan tambahkan keentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Jalankan
ohpm installdi direktorientry, atau klik Sync Now di DevEco Studio.
cd entry
ohpm installHAR 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:
// 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:
- Backend Anda menerbitkan
server_tokensekali pakai untuk pengguna yang sedang masuk (lihat Server token). - Aplikasi meneruskannya ke SDK dan membuka CAPTCHA.
onSuccessmengembalikanpassToken; aplikasi mengirimkannya ke backend Anda.- Backend Anda memvalidasi
passToken(lihat Validasi sisi server).
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:
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
}
}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
| Simbol | Fungsi |
|---|---|
CaptchalaClient.getClient(uiContext) | Titik masuk singleton, terikat ke UIContext halaman Anda. |
CaptchalaConfigBuilder | Builder 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. |
CaptchalaResult | passToken, 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. |
CaptchalaError | code, message, detail. Diteruskan ke onFail (pengguna dapat mencoba lagi) dan onError (error jaringan, konfigurasi, atau sistem). |
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 singletonKonfigurasi
| Setter | Default | Arti |
|---|---|---|
setAppKey(string) | wajib | App Key Anda dari dasbor. |
setAction(string) | default | Aksi bisnis (login, register, pay, …). Harus sama dengan action pada server_token. |
setLang(string) | '' (auto) | Bahasa tantangan, misalnya en, zh-CN. |
setTheme(string) | auto | auto (mengikuti sistem), light, atau dark. |
setServerToken(string | null) | null | server_token yang diterbitkan backend Anda. |
setOnServerTokenExpired(cb) | null | () => Promise<string | null> yang mengambil server_token baru dari backend Anda. |
setTimeout(number) | 10000 | Batas waktu permintaan, ms. |
setEnableVoice(boolean) | true | Menyediakan tantangan audio. |
setEnableOfflineMode(boolean) | false | Mengizinkan jalur cadangan saat gangguan. Hasilnya membawa isOffline / isClientOnly. |
setMaskClosable(boolean) | false | Mengetuk latar belakang menutup dialog. |
setCollectOdid(boolean) | true | Mengirim hash ODID perangkat (lihat Privasi). |
setLoadingStyle(string) | 'spinner' | Indikator pemuatan, lihat Indikator pemuatan. |
setLoadingColor(string | null) | putih | Warna indikator, #RRGGBB atau #RRGGBBAA. |
setLoadingSize(string) | 'medium' | 'small', 'medium', atau 'large'. |
setLoadingDelay(number) | 300 | Milidetik sebelum indikator muncul, 0–5000. |
setDebug(boolean) | false | Log 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().
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 dariverify()hinggaonReady.setLoadingColor:#RRGGBBatau#RRGGBBAA, default putih.setLoadingSize:'small','medium'(default), atau'large'.setLoadingDelay: milidetik,0–5000.
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.
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:
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 installtidak menemukan paket
Jalurfile:bersifat relatif terhadap modulentry. Pastikan file ada dientry/libs/dan namanya sama persis dengan yang ada dioh-package.json5.Versi lama masih dipakai setelah pembaruan
Hapus.harlama darientry/libs/, perbarui versi di jalurfile:, lalu jalankanohpm 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.onErrordengan kodeserver_token_*
Periksa apakahsetActiondi aplikasi sama denganactionyang dipakai saat menerbitkan token, dan apakahsetOnServerTokenExpiredmengembalikan 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