iOS / macOS SDK

SDK platform Apple untuk iOS 15+ dan macOS 11+ (Big Sur) melalui Mac Catalyst, dihantar sebagai .xcframework serta .bundle aset terlokal. Sesuai untuk projek SwiftUI, UIKit dan AppKit.

Demo di GitHub

📦

Captcha-La/iosmacos-demo — contoh lengkap yang boleh dijalankan dengan semua langkah integrasi.

Pemasangan

Tambah CaptchaLa ke Podfile anda (CocoaPods 1.10+):

# Podfile
platform :ios, '13.0'

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

pod install

Atau, jika anda lebih suka integrasi manual:

Download the latest iOS release from the CaptchaLa dashboard. The archive contains:

• Captchala.xcframework — the compiled SDK
• Captchala.bundle — localized resources

Drop both next to your .xcodeproj. The demo project references them by file name; no manual linking is needed beyond keeping their location stable.

Untuk integrasi manual, muat turun xcframework terus: dash.captcha.la/downloads

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

Open the project and run on the simulator, a device, or My Mac (Mac Catalyst):

open YourApp.xcodeproj
# Cmd-R in Xcode

Mula pantas

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

The exact same Swift code runs on iOS, Mac Catalyst, and native macOS. On Catalyst pass any UIViewController. On native macOS use NSViewController and call .verify() without an argument — the SDK presents in its own NSWindow.

API utama

Simbol	Tujuan
CaptchalaClient.shared	Singleton dikongsi. Semua titik masuk bermula di sini.
CaptchalaConfigBuilder()	Builder lancar untuk appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
initialize(config:)	Memohon konfigurasi yang telah dibina. Mengembalikan self untuk dirantai dengan setDelegate.
setDelegate(_:)	Berikan NSObject yang patuh CaptchalaDelegate. SDK menyimpan rujukan lemah.
verify(from: presenter)	Memaparkan CAPTCHA di atas UIViewController yang diberikan (iOS / Catalyst). SDK menolak modal sheet.
CaptchalaResult	Dikembalikan menerusi captcha(didSucceedWith:). Medan: passToken, challengeId, ttl, isOffline, isClientOnly.
onServerTokenExpired { … }	Penutup asinkron yang mengambil semula server_token baru jika yang sebelumnya tamat di tengah cabaran.

Pengesahan di pelayan

Hantar result.passToken (atau result.token) ke backend anda dan sahkan menerusi API CaptchaLa. Jangan dedahkan X-App-Secret dalam kod klien.

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

Lihat Rujukan API untuk endpoint pengesahan penuh dan aliran X-App-Key / X-App-Secret.

Penyelesaian masalah

• Captchala.xcframework tidak ditemui
  .xcframework dan .bundle mesti berada di sebelah Example.xcodeproj. Demo merujuk kedua-duanya melalui nama fail; kekalkan lokasi semasa mengemas kini SDK.

• Destinasi Mac Catalyst tidak kelihatan
  Dalam Xcode, dayakan Mac (Mac Catalyst) di bawah Supported Destinations sasaran anda. Demo menetapkan SUPPORTS_MACCATALYST = YES.

• Modal tidak muncul
  Hantar UIViewController sebenar kepada verify(from:). Demo mengembara UIApplication.connectedScenes untuk mencari pengawal key-window paling atas — salin pembantu itu jika anda hanya memiliki SwiftUI View.

• Rentetan privasi Info.plist diperlukan di macOS
  Untuk sasaran Catalyst / macOS asli, dayakan keupayaan kotak pasir Outgoing Connections (Client). SDK hanya membuat panggilan HTTPS, tiada akses mikrofon atau kamera.

Keperluan

• iOS 15+ (device or simulator)
• macOS 11+ (Big Sur) via Mac Catalyst, macOS 13+ for native targets
• Xcode 15+
• Swift 5.7+ (async/await)