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 を設定する Builder。
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)