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.
- 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.
- Muat turun HAR HarmonyOS, contohnya
captchala-1.2.0.har. - Bandingkan SHA-256 fail dengan nilai yang dipaparkan di halaman muat turun. Jika berbeza, jangan gunakan fail itu.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Salin fail ke
entry/libs/dan tambahkannya dalamentry/oh-package.json5:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}- Jalankan
ohpm installdalam direktorientry, atau klik Sync Now dalam DevEco Studio.
cd entry
ohpm installHAR 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:
// 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:
- Backend anda mengeluarkan
server_tokensekali guna untuk pengguna yang telah log masuk (lihat Server token). - Aplikasi menghantarnya kepada SDK dan membuka CAPTCHA.
onSuccessmengembalikanpassToken; aplikasi menghantarnya ke backend anda.- Backend anda mengesahkan
passToken(lihat Pengesahan di pelayan).
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:
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_) 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
| Simbol | Tujuan |
|---|---|
CaptchalaClient.getClient(uiContext) | Titik masuk singleton, terikat pada UIContext halaman anda. |
CaptchalaConfigBuilder | Builder 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. |
CaptchalaResult | passToken, 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. |
CaptchalaError | code, message, detail. Dihantar kepada onFail (pengguna boleh cuba lagi) dan onError (ralat rangkaian, 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 | Lalai | Maksud |
|---|---|---|
setAppKey(string) | wajib | App Key anda dari papan pemuka. |
setAction(string) | default | Tindakan perniagaan (login, register, pay, …). Mesti sama dengan action pada server_token. |
setLang(string) | '' (auto) | Bahasa cabaran, contohnya en, zh-CN. |
setTheme(string) | auto | auto (mengikut sistem), light atau dark. |
setServerToken(string | null) | null | server_token yang dikeluarkan oleh backend anda. |
setOnServerTokenExpired(cb) | null | () => Promise<string | null> yang mendapatkan server_token baharu daripada backend anda. |
setTimeout(number) | 10000 | Had masa permintaan, ms. |
setEnableVoice(boolean) | true | Menawarkan cabaran audio. |
setEnableOfflineMode(boolean) | false | Membenarkan laluan sandaran semasa gangguan. Keputusannya membawa isOffline / isClientOnly. |
setMaskClosable(boolean) | false | Mengetik latar belakang menutup dialog. |
setCollectOdid(boolean) | true | Menghantar cincangan ODID peranti (lihat Privasi). |
setLoadingStyle(string) | 'spinner' | Penunjuk pemuatan, lihat Penunjuk pemuatan. |
setLoadingColor(string | null) | putih | Warna penunjuk, #RRGGBB atau #RRGGBBAA. |
setLoadingSize(string) | 'medium' | 'small', 'medium' atau 'large'. |
setLoadingDelay(number) | 300 | Milisaat sebelum penunjuk muncul, 0–5000. |
setDebug(boolean) | false | Log 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().
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 dariverify()hinggaonReady.setLoadingColor:#RRGGBBatau#RRGGBBAA, lalai putih.setLoadingSize:'small','medium'(lalai) atau'large'.setLoadingDelay: milisaat,0–5000.
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.
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:
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 installtidak menemui pakej
Laluanfile:adalah relatif kepada modulentry. Pastikan fail berada dalamentry/libs/dan namanya sama tepat dengan yang dalamoh-package.json5.Versi lama masih digunakan selepas naik taraf
Padam.harlama darientry/libs/, kemas kini versi dalam laluanfile:, kemudian jalankanohpm 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.onErrordengan kodserver_token_*
Semak sama adasetActiondalam aplikasi sama denganactionyang digunakan semasa mengeluarkan token, dan sama adasetOnServerTokenExpiredmengembalikan 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