iOS / macOS SDK

Apple 平台 SDK，支援 iOS 15+ 與基於 Mac Catalyst 的 macOS 11+（Big Sur），以 .xcframework 加本地化資源 .bundle 形式發布。SwiftUI / UIKit / AppKit 專案皆可直接接入。

GitHub 上的範例

📦

Captcha-La/iosmacos-demo — 完整可執行範例，包含所有整合步驟。

安裝

在 Podfile 加入 CaptchaLa(CocoaPods 1.10+):

# Podfile
platform :ios, '13.0'

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

pod install

如果你偏好手動整合:

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.

手動整合請直接下載 xcframework: 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

快速開始

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 一覽

符號	用途
CaptchalaClient.shared	共享單例，所有入口皆透過它存取。
CaptchalaConfigBuilder()	鏈式 Builder，用於設定 appKey、action、lang、theme、enableVoice、enableOfflineMode、serverToken。
initialize(config:)	套用已建立的設定。回傳 self，便於串接 setDelegate。
setDelegate(_:)	傳入實作 CaptchalaDelegate 的 NSObject。SDK 持弱引用。
verify(from: presenter)	在指定的 UIViewController 上顯示驗證碼（iOS / Catalyst），SDK 彈出 modal sheet。
CaptchalaResult	透過 captcha(didSucceedWith:) 回呼回傳。欄位：passToken、challengeId、ttl、isOffline、isClientOnly。
onServerTokenExpired { … }	非同步閉包，當前 server_token 在挑戰過程中過期時，自動取得新 token。

伺服器端驗證

將 result.passToken（或 result.token）送到你的後端，再呼叫 CaptchaLa API 驗證。切勿在用戶端程式碼中暴露 X-App-Secret。

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

完整驗證端點及 X-App-Key / X-App-Secret 流程請見 API 參考。

常見問題

• 找不到 Captchala.xcframework
.xcframework 與 .bundle 必須和 Example.xcodeproj 同層。demo 透過檔名引用它們，更新 SDK 時保持位置不變即可。

• 找不到 Mac Catalyst destination
  在 Xcode 中，於 target 的 Supported Destinations 勾選 Mac (Mac Catalyst)。demo target 預設 SUPPORTS_MACCATALYST = YES。

• modal 沒有彈出
  verify(from:) 必須傳入實際的 UIViewController。demo 走訪 UIApplication.connectedScenes 找最上層的 key-window controller，如果只有 SwiftUI View，複製這段 helper 即可。

• macOS 上需要 Info.plist 隱私描述
  針對 Catalyst / 原生 macOS target，開啟 Outgoing Connections (Client) 沙箱權限。SDK 僅發起 HTTPS 請求，不存取麥克風或攝影機。

系統需求

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