iOS / macOS SDK

SDK nền tảng Apple cho iOS 15+ và macOS 11+ (Big Sur) qua Mac Catalyst, phân phối dưới dạng .xcframework cùng .bundle tài nguyên đa ngôn ngữ. Tích hợp được vào dự án SwiftUI, UIKit và AppKit.

Demo trên GitHub

📦

Captcha-La/iosmacos-demo — ví dụ đầy đủ, có thể chạy được, kèm mọi bước tích hợp.

Cài đặt

Thêm CaptchaLa vào Podfile của bạn (CocoaPods 1.10+):

# Podfile
platform :ios, '13.0'

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

pod install

Hoặc, nếu bạn thích tích hợp thủ công:

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.

Để tích hợp thủ công, tải xcframework trực tiếp: 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

Bắt đầu nhanh

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 chính

Ký hiệu	Mục đích
CaptchalaClient.shared	Singleton dùng chung. Mọi điểm vào đều thông qua nó.
CaptchalaConfigBuilder()	Builder dạng fluent cho appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
initialize(config:)	Áp dụng cấu hình đã build. Trả về self để chain với setDelegate.
setDelegate(_:)	Truyền vào NSObject tuân thủ CaptchalaDelegate. SDK giữ tham chiếu yếu.
verify(from: presenter)	Hiển thị CAPTCHA trên UIViewController được chỉ định (iOS / Catalyst). SDK trình bày dưới dạng modal sheet.
CaptchalaResult	Trả về qua captcha(didSucceedWith:). Trường: passToken, challengeId, ttl, isOffline, isClientOnly.
onServerTokenExpired { … }	Closure bất đồng bộ, lấy lại server_token mới khi token trước hết hạn giữa chừng.

Xác thực phía máy chủ

Chuyển result.passToken (hoặc result.token) tới backend của bạn rồi xác thực qua API CaptchaLa. Tuyệt đối không để lộ X-App-Secret trong mã 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>" }

Xem Tài liệu API để biết chi tiết endpoint xác thực và quy trình X-App-Key / X-App-Secret.

Khắc phục sự cố

• Không tìm thấy Captchala.xcframework
.xcframework và .bundle phải nằm cạnh Example.xcodeproj. Demo tham chiếu chúng theo tên file; giữ nguyên vị trí khi cập nhật SDK.

• Không thấy destination Mac Catalyst
  Trong Xcode, bật Mac (Mac Catalyst) trong Supported Destinations của target. Target demo có SUPPORTS_MACCATALYST = YES.

• Modal không hiển thị
  Hãy truyền một UIViewController thật vào verify(from:). Demo duyệt UIApplication.connectedScenes để tìm key-window controller trên cùng — sao chép helper đó nếu bạn chỉ có SwiftUI View.

• Cần chuỗi quyền riêng tư trong Info.plist trên macOS
  Với target Catalyst / macOS gốc, bật capability sandbox Outgoing Connections (Client). SDK chỉ gọi HTTPS, không truy cập microphone hay camera.

Yêu cầu

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