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.