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

# SDK iOS / macOS

SDK pour plateformes Apple : **iOS 15+** et **macOS 11+ (Big Sur)** via Mac Catalyst, livré sous forme d'un `.xcframework` plus un `.bundle` de ressources localisées. Intégrable dans les projets SwiftUI, UIKit et AppKit.

## Démo sur GitHub

::: tip 📦
[Captcha-La/iosmacos-demo](https://github.com/Captcha-La/iosmacos-demo) — exemple complet exécutable avec chaque étape d'intégration.
:::

## Installation

Ajoutez CaptchaLa à votre `Podfile` (CocoaPods 1.10+) :

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

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

```bash
pod install
```

Ou, si vous préférez l'intégration manuelle :

Téléchargez la dernière version iOS depuis le [tableau de bord CaptchaLa](https://dash.captcha.la). L'archive contient :

- `Captchala.xcframework` — le SDK compilé
- `Captchala.bundle` — les ressources localisées

Déposez les deux à côté de votre `.xcodeproj`. Le projet de démo les référence par leur nom de fichier ; aucune liaison manuelle n'est nécessaire au-delà du maintien d'un emplacement stable.


Pour une intégration manuelle, téléchargez le xcframework directement : [dash.captcha.la/downloads](https://dash.captcha.la/downloads)

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

Ouvrez le projet et exécutez sur le simulateur, un appareil ou **My Mac (Mac Catalyst)** :

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

## Démarrage rapide

```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 et macOS natif
Le même code Swift s'exécute sur iOS, Mac Catalyst et macOS natif. Sous Catalyst, passez n'importe quel `UIViewController`. Sur macOS natif, utilisez `NSViewController` et appelez `.verify()` sans argument — le SDK s'affiche dans sa propre `NSWindow`.
:::

## Surface de l'API

| Symbole | Rôle |
| --- | --- |
| `CaptchalaClient.shared` | Singleton partagé. Tous les points d'entrée en dépendent. |
| `CaptchalaConfigBuilder()` | Builder fluide. Définissez `appKey`, `action`, `lang`, `theme`, `enableVoice`, `enableOfflineMode`, `serverToken`. |
| `initialize(config:)` | Applique la configuration construite. Renvoie `self` pour chaîner `setDelegate`. |
| `setDelegate(_:)` | Fournit un `NSObject` conforme à `CaptchalaDelegate`. Le SDK conserve une référence faible. |
| `verify(from: presenter)` | Présente le CAPTCHA au-dessus du UIViewController fourni (iOS / Catalyst). Le SDK affiche une feuille modale. |
| `CaptchalaResult` | Renvoyé via `captcha(didSucceedWith:)`. Champs : `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. |
| `onServerTokenExpired { … }` | Closure asynchrone qui récupère un `server_token` frais si le précédent expire en cours de challenge. |

## Validation côté serveur

Transmettez `result.passToken` (ou `result.token`) à votre backend et validez-le auprès de l'API CaptchaLa. N'exposez jamais `X-App-Secret` dans le code client.

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

Consultez la [Référence de l'API](../api-reference) pour l'endpoint de validation complet et le flux `X-App-Key` / `X-App-Secret`.

## Dépannage

- **`Captchala.xcframework` introuvable**  
  Le `.xcframework` et le `.bundle` doivent être placés à côté de `Example.xcodeproj`. La démo référence les deux par leur nom de fichier ; conservez leur emplacement stable lors de la mise à jour du SDK.

- **Destination Mac Catalyst manquante**  
  Dans Xcode, activez *Mac (Mac Catalyst)* sous *Supported Destinations* de votre cible. La cible de démo est livrée avec `SUPPORTS_MACCATALYST = YES`.

- **La modale n'apparaît pas**  
  Passez un véritable `UIViewController` à `verify(from:)`. La démo parcourt `UIApplication.connectedScenes` pour trouver le contrôleur de la fenêtre clé active la plus haute — copiez cet utilitaire si vous n'avez qu'une `View` SwiftUI.

- **Chaînes de confidentialité `Info.plist` sur macOS**  
  Pour les cibles Catalyst / macOS natif, activez la capacité sandbox **Outgoing Connections (Client)**. Le SDK n'effectue que des appels HTTPS, sans accès au microphone ou à la caméra.

## Prérequis

- iOS 15+ (appareil ou simulateur)
- macOS 11+ (Big Sur) via Mac Catalyst, macOS 13+ pour les cibles natives
- Xcode 15+
- Swift 5.7+ (async/await)