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

如果你偏好手動整合:

從 CaptchaLa 控制台 下載最新 iOS 版本，壓縮檔內含：

• Captchala.xcframework — 已編譯的 SDK
• Captchala.bundle — 本地化資源

將兩者放在你的 .xcodeproj 旁。demo 專案以檔名引用，只要位置不變，無需額外手動連結。

手動整合請直接下載 xcframework: dash.captcha.la/downloads

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

開啟專案後可選擇在模擬器、實體裝置或 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 與原生 macOS

完全相同的 Swift 程式碼可在 iOS、Mac Catalyst 與原生 macOS 上執行。Catalyst 傳入任一 UIViewController 即可；原生 macOS 使用 NSViewController，並呼叫不帶參數的 .verify() —— SDK 會在自有 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>" }

完整驗證端點及 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+（實體裝置或模擬器）
• macOS 11+（Big Sur）透過 Mac Catalyst；原生 target 需 macOS 13+
• Xcode 15+
• Swift 5.7+（async/await）