--- title: HarmonyOS SDK description: "HarmonyOS NEXT için CaptchaLa SDK (ArkTS): panelden HAR kurulumu, doğrulama akışı ve sunucu tarafı doğrulama." --- # HarmonyOS SDK ::: info SDK 1.2.0 SDK 1.2.0 için güncellendi. Bazı ayrıntılar yalnızca İngilizce olarak mevcuttur: [İngilizce sayfaya](/sdk/harmony) ve [değişiklik günlüğüne](/changelog#sdk-1-2-0) 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](./android) kullanın. ::: ## Kurulum SDK **ohpm'de yayımlanmaz**. HAR'ı panelden indirip yerel bağımlılık olarak eklersiniz. 1. Panelde oturum açın ve [**SDK indirmeleri**](https://dash.captcha.la/sdk-downloads?platform=harmony) sayfasını açın. Aynı sayfada DevEco Studio'da açabileceğiniz bir HarmonyOS demo projesi (kaynak kodu) da bulunur. 2. HarmonyOS HAR dosyasını indirin, örneğin `captchala-1.2.0.har`. 3. Dosyanın SHA-256 değerini indirme sayfasında gösterilen değerle karşılaştırın. Farklıysa dosyayı kullanmayın. ```bash # macOS / Linux shasum -a 256 captchala-1.2.0.har # Windows (PowerShell) Get-FileHash captchala-1.2.0.har -Algorithm SHA256 ``` 4. Dosyayı `entry/libs/` klasörüne kopyalayın ve `entry/oh-package.json5` dosyasına ekleyin: ```json5 // entry/oh-package.json5 { "dependencies": { "@captchala/captchala": "file:./libs/captchala-1.2.0.har" } } ``` 5. `entry` dizininde `ohpm install` komutunu çalıştırın ya da DevEco Studio'da **Sync Now**'a tıklayın. ```bash cd entry ohpm install ``` HAR, 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: ```json5 // 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ış: 1. Arka ucunuz oturum açmış kullanıcı için tek kullanımlık bir `server_token` üretir (bkz. [Server token](#server-token)). 2. Uygulama bunu SDK'ya verir ve CAPTCHA'yı açar. 3. `onSuccess` bir `passToken` döndürür; uygulama bunu arka ucunuza gönderir. 4. Arka ucunuz `passToken`'ı doğrular (bkz. [Sunucu tarafı doğrulama](#server-side-validation)). ```ts import { CaptchalaClient, CaptchalaConfigBuilder, CaptchalaListener, CaptchalaResult, CaptchalaError } from '@captchala/captchala'; @Entry @Component struct Login { private async verify(): Promise { // 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} `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: ```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 } } ``` `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ı](../api-reference#server-token)'na bakın veya [PHP](./server-php) / [Go](./server-go) sunucu SDK'sını kullanın. ## API yüzeyi {#api-surface} | 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ı](#token-expiry)) 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. | ```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 ``` ### Yapılandırma {#configuration} | 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`. | | `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](#privacy)). | | `setLoadingStyle(string)` | `'spinner'` | Yükleme göstergesi, bkz. [Yükleme göstergesi](#loading-indicator). | | `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ı {#token-expiry} `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. ```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`, 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 {#loading-indicator} 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ından `onReady` gelene kadar kendi göstergenizi gösterin. - `setLoadingColor`: `#RRGGBB` veya `#RRGGBBAA`, varsayılan beyaz. - `setLoadingSize`: `'small'`, `'medium'` (varsayılan) veya `'large'`. - `setLoadingDelay`: milisaniye, `0`–`5000`. ```ts const config = new CaptchalaConfigBuilder() .setAppKey('YOUR_APP_KEY') .setLoadingStyle('dots') .setLoadingColor('#3B82F6') .setLoadingSize('small') .setLoadingDelay(500) .build(); ``` ## Sunucu tarafı doğrulama {#server-side-validation} `result.passToken` değerini arka ucunuza iletin ve CaptchaLa API'si ile doğrulayın. `X-App-Secret`'ı asla uygulamaya koymayın. ```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": "", "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ı](../api-reference)'na bakın. ## Gizlilik {#privacy} 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: ```ts 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 {#troubleshooting} - **`ohpm install` paketi bulamıyor** `file:` yolu `entry` modülüne göredir. Dosyanın `entry/libs/` içinde olduğunu ve adının `oh-package.json5` içindekiyle birebir aynı olduğunu kontrol edin. - **Güncellemeden sonra eski sürüm kullanılmaya devam ediyor** Eski `.har` dosyasını `entry/libs/` klasöründen silin, `file:` yolundaki sürümü güncelleyin ve `ohpm install` komutunu (veya **Sync Now**) yeniden çalıştırın. - **SHA-256 eşleşmiyor** HAR'ı [**SDK indirmeleri**](https://dash.captcha.la/sdk-downloads?platform=harmony) sayfasından yeniden indirin. Sağlama toplamı paneldekiyle eşleşmeyen bir dosyayı yayımlamayın. - **`onError` bir `server_token_*` koduyla dönüyor** Uygulamadaki `setAction` değerinin token üretilirken kullanılan `action` ile aynı olduğunu ve `setOnServerTokenExpired`'ı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](./android) kullanın. ## Gereksinimler {#requirements} - 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`