iOS / macOS SDK

SDK platform Apple untuk iOS 15+ dan macOS 11+ (Big Sur) melalui Mac Catalyst, didistribusikan sebagai .xcframework plus .bundle aset terlokalisasi. Dapat langsung digunakan pada proyek SwiftUI, UIKit, dan AppKit.

Demo di GitHub

📦

Captcha-La/iosmacos-demo — contoh lengkap dan dapat dijalankan dengan seluruh langkah integrasi.

Instalasi

Tambahkan CaptchaLa ke Podfile Anda (CocoaPods 1.10+):

# Podfile
platform :ios, '13.0'

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

pod install

Atau, jika Anda lebih suka integrasi manual:

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.

Untuk integrasi manual, unduh xcframework langsung: 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

Mulai cepat

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 utama

Simbol	Tujuan
CaptchalaClient.shared	Singleton bersama. Semua titik masuk berasal dari sini.
CaptchalaConfigBuilder()	Builder fluent untuk appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
initialize(config:)	Menerapkan konfigurasi yang sudah dibangun. Mengembalikan self agar bisa dirantai dengan setDelegate.
setDelegate(_:)	Berikan NSObject yang konforman dengan CaptchalaDelegate. SDK menyimpan referensi lemah.
verify(from: presenter)	Menampilkan CAPTCHA di atas UIViewController yang diberikan (iOS / Catalyst). SDK memunculkan modal sheet.
CaptchalaResult	Dikembalikan lewat captcha(didSucceedWith:). Field: passToken, challengeId, ttl, isOffline, isClientOnly.
onServerTokenExpired { … }	Closure asinkron yang mengambil ulang server_token baru bila yang sebelumnya kedaluwarsa di tengah challenge.

Validasi sisi server

Teruskan result.passToken (atau result.token) ke backend Anda lalu validasi melalui API CaptchaLa. Jangan pernah mengekspos X-App-Secret di kode klien.

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>" }

Lihat Referensi API untuk endpoint validasi lengkap dan alur X-App-Key / X-App-Secret.

Pemecahan masalah

• Captchala.xcframework tidak ditemukan
  .xcframework dan .bundle harus berada di samping Example.xcodeproj. Demo mereferensikan keduanya berdasarkan nama file; pertahankan lokasinya saat memperbarui SDK.

• Destination Mac Catalyst tidak muncul
  Di Xcode, aktifkan Mac (Mac Catalyst) di Supported Destinations target Anda. Demo memakai SUPPORTS_MACCATALYST = YES.

• Modal tidak muncul
  Berikan UIViewController asli ke verify(from:). Demo menelusuri UIApplication.connectedScenes untuk menemukan controller key-window paling atas — salin helper tersebut jika Anda hanya punya View SwiftUI.

• Memerlukan string privasi Info.plist di macOS
  Untuk target Catalyst / macOS native, aktifkan kapabilitas sandbox Outgoing Connections (Client). SDK hanya melakukan panggilan HTTPS, tidak mengakses mikrofon atau kamera.

Persyaratan

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