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()	appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken 을 설정하는 빌더.
initialize(config:)	빌드된 설정을 적용합니다. self 를 반환해 setDelegate 를 체이닝할 수 있습니다.
setDelegate(_:)	CaptchalaDelegate 를 채택한 NSObject 를 전달합니다. SDK 는 약한 참조로 보관합니다.
verify(from: presenter)	지정한 UIViewController(iOS / Catalyst) 위에 CAPTCHA 를 모달 시트로 표시합니다.
CaptchalaResult	captcha(didSucceedWith:) 콜백으로 반환됩니다. 필드: passToken, challengeId, ttl, isOffline, isClientOnly.
onServerTokenExpired { … }	챌린지 중 기존 server_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 와 같은 위치에 두세요. 데모는 파일명으로 참조하므로 SDK 업데이트 시 경로를 바꾸지 마세요.

• Mac Catalyst destination 이 보이지 않음
  Xcode 에서 타깃의 Supported Destinations 에 Mac (Mac Catalyst) 을 활성화하세요. 데모는 SUPPORTS_MACCATALYST = YES 입니다.

• 모달이 나타나지 않음
  verify(from:) 에 실제 UIViewController 를 전달하세요. 데모는 UIApplication.connectedScenes 를 순회해 최상단 key-window 컨트롤러를 얻습니다 — SwiftUI View 만 있다면 이 헬퍼를 복사하세요.

• macOS 에서 Info.plist 개인정보 문구 필요
  Catalyst / 네이티브 macOS 타깃에서는 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)