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

📦

Captcha-La/iosmacos-demo — exemple complet exécutable avec chaque étape d'intégration.

Installation

Ajoutez CaptchaLa à votre Podfile (CocoaPods 1.10+) :

# Podfile
platform :ios, '13.0'

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

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

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

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

open YourApp.xcodeproj
# Cmd-R in Xcode

Démarrage rapide

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

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

Consultez la Référence de l'API 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)