iOS / macOS SDK

iOS 15+ ve macOS 11+ (Big Sur) için Apple platform SDK'sı; Mac Catalyst aracılığıyla bir .xcframework ve yerelleştirilmiş varlıkları içeren bir .bundle olarak gelir. SwiftUI, UIKit ve AppKit projeleri için drop-in.

GitHub'da demo

📦

Captcha-La/iosmacos-demo — her entegrasyon adımını içeren tam çalıştırılabilir örnek.

Kurulum

CaptchaLa'yı Podfile'ınıza ekleyin (CocoaPods 1.10+):

# Podfile
platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!
  pod 'Captchala', '~> 1.0.2'
end

pod install

Veya manuel entegrasyonu tercih ederseniz:

En son iOS sürümünü CaptchaLa panelinden indirin. Arşiv şunları içerir:

• Captchala.xcframework — derlenmiş SDK
• Captchala.bundle — yerelleştirilmiş kaynaklar

İkisini de .xcodeproj dosyanızın yanına bırakın. Demo projesi bunlara dosya adıyla referans verir; konumlarını sabit tuttuğunuz sürece manuel bağlama gerekmez.

Manuel entegrasyon için xcframework'ü doğrudan indirin: dash.captcha.la/downloads

YourApp/
├── YourApp.xcodeproj
├── YourApp/
├── Captchala.xcframework
└── Captchala.bundle

Projeyi açın ve simülatörde, bir cihazda veya My Mac (Mac Catalyst)'ta çalıştırın:

open YourApp.xcodeproj
# Cmd-R in Xcode

Hızlı başlangıç

import SwiftUI
import Captchala

final class CaptchaDelegateBridge: NSObject, CaptchalaDelegate {
    var onSuccess: ((CaptchalaResult) -> Void)?
    var onFailure: ((CaptchalaError) -> Void)?
    var onClose:   (() -> Void)?

    func captcha(didSucceedWith result: CaptchalaResult) { onSuccess?(result) }
    func captcha(didFailWithError error: CaptchalaError) { onFailure?(error) }
    func captchaDidClose() { onClose?() }
}

struct LoginView: View {
    @State private var bridge = CaptchaDelegateBridge()
    @State private var status = "Tap to verify"

    var body: some View {
        Button("Verify with CAPTCHA", action: startVerify)
        Text(status).font(.caption)
    }

    private func startVerify() {
        bridge.onSuccess = { r in
            // Send r.passToken to your backend for validation.
            status = "OK: \(r.passToken)"
        }
        bridge.onFailure = { e in status = "ERROR [\(e.code)] \(e.message)" }

        Task { @MainActor in
            // 1. Fetch a one-shot server_token from YOUR backend.
            let token = await fetchServerTokenFromYourBackend()

            // 2. Build config and present.
            let config = CaptchalaConfigBuilder()
                .appKey("YOUR_APP_KEY")
                .action("login")
                .lang("en")              // en, zh-CN, zh-TW, ja, ko, ms, vi, id
                .theme("light")          // "light" | "dark"
                .enableVoice(true)
                .enableOfflineMode(true)
                .serverToken(token)
                .onServerTokenExpired { await fetchServerTokenFromYourBackend() }
                .build()

            guard let presenter = topViewController() else { return }
            CaptchalaClient.shared
                .initialize(config: config)
                .setDelegate(bridge)
                .verify(from: presenter)
        }
    }
}

Mac Catalyst & native macOS

Aynı Swift kodu iOS, Mac Catalyst ve native macOS üzerinde çalışır. Catalyst'te herhangi bir UIViewController geçirin. Native macOS'ta NSViewController kullanın ve .verify() değerini argümansız çağırın — SDK kendi NSWindow'unda sunar.

API yüzeyi

Sembol	Amaç
CaptchalaClient.shared	Paylaşılan singleton. Tüm giriş noktaları buna bağlıdır.
CaptchalaConfigBuilder()	Akıcı builder. appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken ayarlayın.
initialize(config:)	Yapılandırılmış config'i uygula. setDelegate ile zincirleyebilmeniz için self döndürür.
setDelegate(_:)	CaptchalaDelegate'e uyan bir NSObject sağlayın. SDK weak referans tutar.
verify(from: presenter)	CAPTCHA'yı verilen UIViewController üzerinde sunar (iOS / Catalyst). SDK modal bir sheet açar.
CaptchalaResult	captcha(didSucceedWith:) ile döner. Alanlar: passToken, challengeId, ttl, isOffline, isClientOnly.
onServerTokenExpired { … }	Önceki token challenge ortasında sona ererse yeni bir server_token getiren async closure.

Sunucu tarafı doğrulama

result.passToken (veya result.token) değerini backend'inize iletip CaptchaLa API'sine karşı doğrulayın. X-App-Secret değerini asla istemci kodunda açmayın.

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<result.passToken>", "client_ip": "<end-user IP>" }

Tam doğrulama uç noktası ve X-App-Key / X-App-Secret akışı için API Referansı'na bakın.

Sorun giderme

• Captchala.xcframework bulunamadı
  .xcframework ve .bundle, Example.xcodeproj dosyasının yanında yer almalıdır. Demo, ikisini de dosya adıyla referans gösterir; SDK güncellerken konumlarını sabit tutun.

• Mac Catalyst hedefi eksik
  Xcode'da hedefinizin Supported Destinations altında Mac (Mac Catalyst) seçeneğini etkinleştirin. Demo hedefi SUPPORTS_MACCATALYST = YES ile gelir.

• Modal görünmüyor
  verify(from:) çağrısına gerçek bir UIViewController geçirin. Demo, en üstteki aktif key-window controller'ını bulmak için UIApplication.connectedScenes üzerinde gezinir — yalnızca bir SwiftUI View'unuz varsa o yardımcıyı kopyalayın.

• macOS'ta Info.plist gizlilik dizgileri
  Catalyst / native macOS hedefleri için Outgoing Connections (Client) sandbox yetkisini etkinleştirin. SDK yalnızca HTTPS çağrıları yapar; mikrofon veya kamera erişimi yoktur.

Gereksinimler

• iOS 15+ (cihaz veya simülatör)
• macOS 11+ (Big Sur) Mac Catalyst aracılığıyla, native hedefler için macOS 13+
• Xcode 15+
• Swift 5.7+ (async/await)