iOS Quickstart

Use CircleBox SDK and CircleBoxCloud in Swift apps with SPM.

Install (Git Tag)

Add the repository as a Swift Package dependency:

.package(url: "https://github.com/jeremiahseun/circle-box.git", from: "0.3.1") 

Xcode setup (app project)

1. Open your iOS app in Xcode.
2. File -> Add Package Dependencies....
3. URL: https://github.com/jeremiahseun/circle-box.git.
4. Dependency rule: Up to Next Major with version 0.3.1.
5. Add products:
   • CircleBoxSDK (required)
   • CircleBoxCloud (optional cloud uploader)
   • CircleBoxIntegrations (optional Sentry/PostHog mappers)

Important:

• Add the package URL once (circle-box) and select products from it.
• Do not add separate package references that point to ios/CircleBoxSDK or ios/CircleBoxCloud, or Xcode will show duplicate target-name conflicts.

Select products:

• CircleBoxSDK
• CircleBoxCloud (optional)
• CircleBoxIntegrations (optional adapter helpers)

Core Setup

Initialize once at startup.

SwiftUI app

import SwiftUI import CircleBoxSDK @main struct MyApp: App { init() { CircleBox.start(config: .default) } var body: some Scene { WindowGroup { ContentView() } } } 

UIKit app

import UIKit import CircleBoxSDK @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil ) -> Bool { CircleBox.start(config: .default) return true } } 

Call CircleBox.start once per process launch.

Then use breadcrumbs and export APIs anywhere in app code:

import CircleBoxSDK CircleBox.breadcrumb("checkout_started", attrs: ["flow": "standard"]) 

Pending Crash Export

if CircleBox.hasPendingCrashReport() { let paths = try CircleBox.exportLogs(formats: [.json, .csv, .jsonGzip, .summary]) print(paths) } 

Optional Cloud Upload

Start cloud companion in the same startup path right after CircleBox.start(...):

import CircleBoxCloud CircleBoxCloud.start( config: CircleBoxCloudConfig( endpoint: URL(string: "https://circlebox.seunjeremiah.workers.dev")!, ingestKey: "paste_ingest_key_from_control_plane", flushIntervalSec: 15, immediateFlushOnHighSignal: true ) ) 

Optional Adapter Use

Use CircleBoxIntegrations to map exports into Sentry breadcrumbs or PostHog properties without pulling those SDKs into core CircleBox.