Skip to content

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.

  1. 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.
  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
  1. 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"
  }
}
  1. 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).
  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).
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'ı 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ı'na bakın veya PHP / Go sunucu SDK'sını kullanın.

API yüzeyi ​

SembolAmaç
CaptchalaClient.getClient(uiContext)Sayfanızın UIContext'ine bağlı singleton giriş noktası.
CaptchalaConfigBuilderYapı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.
CaptchalaResultpassToken, 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.
CaptchalaErrorcode, 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 ​

SetterVarsayılanAnlamı
setAppKey(string)zorunluPaneldeki 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)autoauto (sistemi izler), light veya dark.
setServerToken(string | null)nullArka ucunuzun ürettiği server_token.
setOnServerTokenExpired(cb)nullArka ucunuzdan yeni bir server_token alan () => Promise<string | null>.
setTimeout(number)10000İstek zaman aşımı, ms.
setEnableVoice(boolean)trueSesli doğrulamayı sunar.
setEnableOfflineMode(boolean)falseKesinti durumunda yedek yolu etkinleştirir. Sonuçlar isOffline / isClientOnly taşır.
setMaskClosable(boolean)falseArka plana dokunmak iletişim kutusunu kapatır.
setCollectOdid(boolean)trueCihaz ODID'sinin hash'ini gönderir (bkz. Gizlilik).
setLoadingStyle(string)'spinner'Yükleme göstergesi, bkz. Yükleme göstergesi.
setLoadingColor(string | null)beyazGösterge rengi, #RRGGBB veya #RRGGBBAA.
setLoadingSize(string)'medium''small', 'medium' veya 'large'.
setLoadingDelay(number)300Gösterge görünmeden önceki milisaniye, 0–5000.
setDebug(boolean)falseGeliş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.

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 ​

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 ​

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": "<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:

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 ​

  • 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 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 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

MIT-licensed examples · CaptchaLa is operated independently