---
title: iOS / macOS SDK
---

# 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

::: tip 📦
[Captcha-La/iosmacos-demo](https://github.com/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+):

```ruby
# Podfile
platform :ios, '13.0'

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

```bash
pod install
```

Veya manuel entegrasyonu tercih ederseniz:

En son iOS sürümünü [CaptchaLa panelinden](https://dash.captcha.la) 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](https://dash.captcha.la/downloads)

```text
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:

```bash
open YourApp.xcodeproj
# Cmd-R in Xcode
```

## Hızlı başlangıç

```swift
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)
        }
    }
}
```

::: tip 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.

```bash
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>" }
```

Tam doğrulama uç noktası ve `X-App-Key` / `X-App-Secret` akışı için [API Referansı](../api-reference)'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)