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)