HarmonyOS SDK
SDK 1.2.0
SDK 1.2.0 için güncellendi. Bazı ayrıntılar yalnızca İngilizce olarak mevcuttur: İngilizce sayfaya ve değişiklik günlüğüne bakın.
HarmonyOS NEXT (API 12 / HarmonyOS 5.0.0 ve üzeri) için ArkTS SDK'sı; tek bir .har (@captchala/captchala) olarak dağıtılır. Güncel sürüm: 1.2.0. Doğrulama akışı Android ve iOS SDK'larıyla aynıdır: doğrulama sayfanızın üzerinde bir iletişim kutusunda açılır ve döndürülen passToken arka ucunuz tarafından doğrulanır.
INFO
HarmonyOS 4.x ve öncesi Android uygulamalarını çalıştırır. Bu cihazlarda Android SDK kullanın.
Kurulum
SDK ohpm'de yayımlanmaz. HAR'ı panelden indirip yerel bağımlılık olarak eklersiniz.
- Panelde oturum açın ve SDK indirmeleri sayfasını açın. Aynı sayfada DevEco Studio'da açabileceğiniz bir HarmonyOS demo projesi (kaynak kodu) da bulunur.
- HarmonyOS HAR dosyasını indirin, örneğin
captchala-1.2.0.har. - Dosyanın SHA-256 değerini indirme sayfasında gösterilen değerle karşılaştırın. Farklıysa dosyayı kullanmayın.
# macOS / Linux
shasum -a 256 captchala-1.2.0.har
# Windows (PowerShell)
Get-FileHash captchala-1.2.0.har -Algorithm SHA256- Dosyayı
entry/libs/klasörüne kopyalayın veentry/oh-package.json5dosyasına ekleyin:
// entry/oh-package.json5
{
"dependencies": {
"@captchala/captchala": "file:./libs/captchala-1.2.0.har"
}
}entrydizinindeohpm installkomutunu çalıştırın ya da DevEco Studio'da Sync Now'a tıklayın.
cd entry
ohpm installHAR, yalnızca aşağıda listelenen genel API'yi sunan, gizlenmiş (obfuscated) bir release derlemesidir. Tüketici gizleme kuralları HAR'ın içinde gelir; release derlemeniz için ek keep kuralı gerekmez.
İzinler
SDK yalnızca tek bir izin kullanır: ohos.permission.INTERNET. Hiçbir zaman çalışma zamanı izni istemez veya izin penceresi göstermez. Entry modülünüzün bu izni bildirdiğinden emin olun:
// entry/src/main/module.json5
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" }
]
}
}Güncelleme
Yeni HAR'ı indirip entry/libs/ klasörüne kopyalayın, entry/oh-package.json5 içindeki file: yolundaki sürümü değiştirin, eski .har dosyasını silin ve ohpm install komutunu yeniden çalıştırın.
Hızlı başlangıç
Akış:
- Arka ucunuz oturum açmış kullanıcı için tek kullanımlık bir
server_tokenüretir (bkz. Server token). - Uygulama bunu SDK'ya verir ve CAPTCHA'yı açar.
onSuccessbirpassTokendöndürür; uygulama bunu arka ucunuza gönderir.- Arka ucunuz
passToken'ı doğrular (bkz. Sunucu tarafı doğrulama).
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'ı uygulama değil, arka ucunuz üretir: X-App-Key + X-App-Secret ile /v1/server/challenge/issue uç noktasını çağırır. Kendi kullanıcı kimliğinizi bind_uid olarak gönderin; böylece token ve ondan elde edilen passToken o kullanıcıya ait olur:
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
}
}data.server_token değerini (sct_ önekli) uygulamaya döndürün. action, setAction'a verilen değerle aynı olmalıdır. setOnServerTokenExpired ayarlıysa, doğrulama sırasında bir token reddedildiğinde SDK kendiliğinden yeni bir token alır ve yeniden dener; özgün hatayı almak için null döndürün.
Kimlik bağlama seçenekleri (bind_uid, bind_ip) yalnızca token üretilirken sunucunuzda ayarlanır. Uygulama bunları hiçbir zaman göndermez. Tüm parametreler için API Referansı'na bakın veya PHP / Go sunucu SDK'sını kullanın.
API yüzeyi
| Sembol | Amaç |
|---|---|
CaptchalaClient.getClient(uiContext) | Sayfanızın UIContext'ine bağlı singleton giriş noktası. |
CaptchalaConfigBuilder | Yapılandırma için akıcı builder (aşağıdaki tabloya bakın). build() bir CaptchalaConfig döndürür. |
init(config) | Yapılandırmayı uygular. İstemciyi döndürdüğü için çağrılar zincirlenebilir. |
setListener(listener) | Bir CaptchalaListener kaydeder. Yalnızca onSuccess zorunludur; onReady, onFail, onError, onClose ve onExpired (bkz. Token süresinin dolması) isteğe bağlıdır. |
verify() | CAPTCHA iletişim kutusunu açar. Sonuç listener üzerinden gelir. |
refresh() / cancel() / dismiss() | Geçerli doğrulamayı yeniler / akışı durdurup iletişim kutusunu kapatır / iletişim kutusunu kapatır. |
CaptchalaClient.destroy() | Singleton'ı serbest bırakır. |
CaptchalaResult | passToken, challengeId, ttl, isOffline, isClientOnly. passToken'ı arka ucunuza gönderin. ttl 1.2.0'dan itibaren kullanımdan kaldırılmıştır: token ömrünü sunucu belirler ve değiştirebilir; onExpired kullanın. |
CaptchalaError | code, message, detail. onFail (kullanıcı yeniden deneyebilir) ve onError (ağ, yapılandırma veya sistem hatası) çağrılarına iletilir. |
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 singletonYapılandırma
| Setter | Varsayılan | Anlamı |
|---|---|---|
setAppKey(string) | zorunlu | Paneldeki App Key'iniz. |
setAction(string) | default | İş eylemi (login, register, pay, …). server_token'ın action değeriyle aynı olmalıdır. |
setLang(string) | '' (auto) | Doğrulama dili, örn. en, zh-CN. |
setTheme(string) | auto | auto (sistemi izler), light veya dark. |
setServerToken(string | null) | null | Arka ucunuzun ürettiği server_token. |
setOnServerTokenExpired(cb) | null | Arka ucunuzdan yeni bir server_token alan () => Promise<string | null>. |
setTimeout(number) | 10000 | İstek zaman aşımı, ms. |
setEnableVoice(boolean) | true | Sesli doğrulamayı sunar. |
setEnableOfflineMode(boolean) | false | Kesinti durumunda yedek yolu etkinleştirir. Sonuçlar isOffline / isClientOnly taşır. |
setMaskClosable(boolean) | false | Arka plana dokunmak iletişim kutusunu kapatır. |
setCollectOdid(boolean) | true | Cihaz ODID'sinin hash'ini gönderir (bkz. Gizlilik). |
setLoadingStyle(string) | 'spinner' | Yükleme göstergesi, bkz. Yükleme göstergesi. |
setLoadingColor(string | null) | beyaz | Gösterge rengi, #RRGGBB veya #RRGGBBAA. |
setLoadingSize(string) | 'medium' | 'small', 'medium' veya 'large'. |
setLoadingDelay(number) | 300 | Gösterge görünmeden önceki milisaniye, 0–5000. |
setDebug(boolean) | false | Geliştirme sırasında ayrıntılı günlük. |
Token süresinin dolması
onSuccess ile gelen pass token, süresi sunucu tarafından belirlenen sınırlı bir süre boyunca geçerlidir. Sayfanız bu süre içinde token'ı kullanmazsa listener'ın onExpired(passToken) metodu bir kez çağrılır; böylece süresi dolmuş bir token göndermek yerine saklanan token'ı temizleyip kullanıcıdan yeniden doğrulama yapmasını isteyebilirsiniz. Yeni bir doğrulamayı verify() ile başlatın.
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, yeni bir verify(), init() veya destroy() çağrısından sonra çağrılmaz. 1.2.0'dan itibaren kullanılabilir.
Yükleme göstergesi
Doğrulama yüklenirken SDK, karartılmış arka planın üzerinde küçük bir gösterge gösterir. Gösterge yalnızca yükleme setLoadingDelay değerinden (varsayılan 300 ms) uzun sürdüğünde görünür ve doğrulama gösterildiğinde kaybolur. 1.2.0'dan itibaren kullanılabilir.
setLoadingStyle:'spinner'(varsayılan, çubuklar),'ring'(dönen bir yay),'dots'veya'none'.'none'ile hiçbir şey gösterilmez:verify()çağrısındanonReadygelene kadar kendi göstergenizi gösterin.setLoadingColor:#RRGGBBveya#RRGGBBAA, varsayılan beyaz.setLoadingSize:'small','medium'(varsayılan) veya'large'.setLoadingDelay: milisaniye,0–5000.
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setLoadingStyle('dots')
.setLoadingColor('#3B82F6')
.setLoadingSize('small')
.setLoadingDelay(500)
.build();Sunucu tarafı doğrulama
result.passToken değerini arka ucunuza iletin ve CaptchaLa API'si ile doğrulayın. X-App-Secret'ı asla uygulamaya koymayın.
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" }İsteği yalnızca data.valid true olduğunda ve data.uid, server_token'ı ürettiğiniz kullanıcıyla eşleştiğinde kabul edin. Token'lar tek kullanımlıktır. Yanıtın tamamı ve hata kodları için API Referansı'na bakın.
Gizlilik
SDK, izin gerektirmeyen bir dizi cihaz özelliğini (model, işletim sistemi sürümü, ekran, yerel ayar, saat dilimi vb.) okur ve bunları yalnızca doğrulama ve dolandırıcılık önleme için kullanır. Varsayılan olarak cihaz ODID'sinin kısaltılmış bir SHA-256 hash'ini de gönderir; ham değeri asla göndermez. OAID, UDID, seri numarası veya hesap verisi toplanmaz. ODID hash'ini kapatmak için:
const config = new CaptchalaConfigBuilder()
.setAppKey('YOUR_APP_KEY')
.setCollectOdid(false) // the ODID is never read
.build();Açık bırakırsanız, gizlilik politikanızda ve AppGallery gizlilik etiketinde dolandırıcılık önleme amacıyla kullanılan bir cihaz tanımlayıcısı beyan edin.
Sorun giderme
ohpm installpaketi bulamıyorfile:yoluentrymodülüne göredir. Dosyanınentry/libs/içinde olduğunu ve adınınoh-package.json5içindekiyle birebir aynı olduğunu kontrol edin.Güncellemeden sonra eski sürüm kullanılmaya devam ediyor
Eski.hardosyasınıentry/libs/klasöründen silin,file:yolundaki sürümü güncelleyin veohpm installkomutunu (veya Sync Now) yeniden çalıştırın.SHA-256 eşleşmiyor
HAR'ı SDK indirmeleri sayfasından yeniden indirin. Sağlama toplamı paneldekiyle eşleşmeyen bir dosyayı yayımlamayın.onErrorbirserver_token_*koduyla dönüyor
UygulamadakisetActiondeğerinin token üretilirken kullanılanactionile aynı olduğunu vesetOnServerTokenExpired'ın yeni bir token döndürdüğünü kontrol edin.Cihaz HarmonyOS 4.x veya öncesini çalıştırıyor
Desteklenmez. Bu cihazlar Android uygulamalarını çalıştırır; Android SDK kullanın.
Gereksinimler
- HarmonyOS NEXT, API 12 (HarmonyOS 5.0.0) veya üzeri, Stage modeli
- Cihaz türleri: telefon, tablet, 2'si 1 arada
- ABI'ler:
arm64-v8a,x86_64(emülatör) ohos.permission.INTERNET