Installation

note

This page documents Bugsee iOS SDK 7.x. Upgrading from 6.x? See the migration guide. For the previous release, see the 6.x installation guide.

Agent-Assisted Setup

Ask your AI coding assistant:

Use curl to download, read and follow: https://docs.bugsee.com/ai/agent-skills/sdk/ios/v7/SKILL.md

Works with Claude Code, Cursor, Copilot, Codex, and more. Learn more

Requirements


iOS	15.0 or later
tvOS	15.0 or later
visionOS	1.0 or later
Swift Package Manager	swift-tools-version 5.9 (Xcode 15 or later)

6.x supported iOS 12; 7.x raises the minimum to iOS 15. tvOS and visionOS are new in 7.x.

warning

Simulator and Mac Catalyst slices are built without the native crash reporter, so crash capture is unavailable there. Run on a real device to exercise crash reporting.

Add the package

Bugsee is distributed through Swift Package Manager:

https://github.com/bugsee/spm

In Xcode choose File → Add Package Dependencies…, paste that URL, and keep the default Up to Next Major Version rule starting at 7.0.0. Add the Bugsee library to your app target.

For a package manifest:

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "YourApp",
    platforms: [
        .iOS(.v15),
    ],
    dependencies: [
        .package(url: "https://github.com/bugsee/spm", from: "7.0.0"),
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: [
                // The package identity is "spm" — the last path component of the URL.
                .product(name: "Bugsee", package: "spm"),
            ]
        ),
    ]
)

The package vends three libraries:

Library	Add it to	What it is
`Bugsee`	Your app target	The SDK.
`BugseeSwiftUI`	Your app target, instead of `Bugsee`	SwiftUI helpers such as `bugseeProtect()`. Links `Bugsee` as well. See SwiftUI.
`BugseeCrashExtension`	A Crash Reporter Extension target only (iOS 27+)	See Crash Report Extension.

Pre-release versions

To install a pre-release version (one with a suffix, such as -beta1), set the dependency rule to Exact Version. Swift Package Manager keeps pre-release versions out of version ranges, so "Up to Next Major Version" resolves only released versions.

Direct download

For integrations that cannot resolve a Swift package — Unity projects, or any build that embeds frameworks by hand — download the XCFramework. It is the same archive the Swift package resolves:

https://download.bugsee.com/sdk/ios/spm/Bugsee-<version>.zip

Drag Bugsee.xcframework into your target's Frameworks, Libraries, and Embedded Content section and set it to Embed & Sign.

The archive also contains a Tools/ folder with the BugseeAgent and BugseeClean scripts. Keep it inside the folder that contains your .xcodeproj, where the dSYM upload script looks for BugseeAgent.

info

CocoaPods and Carthage are not supported in 7.x. Projects still on either one should move to Swift Package Manager or to the direct download above.

Optional: in-app feedback

The feedback/chat feature is a separate package, BugseeFeedback, layered on top of the core SDK, for iOS only. Add it only if your app uses in-app feedback:

https://github.com/bugsee/feedback-spm

Use the Exact Version rule, at the same version as the core SDK: each BugseeFeedback release requires that core version exactly, so change both versions together when you upgrade. In a package manifest:

dependencies: [
    .package(url: "https://github.com/bugsee/spm", exact: "7.0.1"),
    .package(url: "https://github.com/bugsee/feedback-spm", exact: "7.0.1"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "Bugsee", package: "spm"),
            // The package identity is "feedback-spm".
            .product(name: "BugseeFeedback", package: "feedback-spm"),
        ]
    ),
]

See Feedback for registering the package and showing the chat.

Initialization

Locate your app delegate and launch the SDK in application:didFinishLaunchingWithOptions::

Objective-C
Swift

@import Bugsee;

//...

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...other initialization code

    [Bugsee launchWithToken:@"<your_app_token>"];

    return YES;
}

import Bugsee

//...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...other initialization code

    Bugsee.launch(token: "<your_app_token>")

    return true
}

If your app uses the SwiftUI App life cycle, launch Bugsee from your App's initializer instead. See SwiftUI.

Launching with options

Options are passed either as a BugseeOptions object or as a dictionary keyed by the BugseeOption* constants.

Objective-C
Swift

BugseeOptions *options = [BugseeOptions defaultOptions];
options.shakeToReport = YES;

// Options that have no BugseeOptions property are set by key:
[options updateLaunchOptions:@{
    BugseeOptionCaptureBreadcrumbs : @YES,
}];

[Bugsee launchWithToken:@"<your_app_token>" options:options];

let options = BugseeOptions.default()
options.shakeToReport = true

// Options that have no BugseeOptions property are set by key:
options.updateLaunch([
    BugseeOptionCaptureBreadcrumbs: true,
])

Bugsee.launch(token: "<your_app_token>", options: options)

Use the BugseeOption* constants as keys. Every option, its default and its BugseeOptions property are listed in Configuration.

Knowing when the SDK is running

Capture is brought up off the main thread, so launchWithToken: returns before the SDK is fully running. Called while the app is in the background state or before UIApplication exists, as from application:didFinishLaunchingWithOptions: in a scene-based app or from a SwiftUI App initializer, the launch also waits for the app to become active; the crash handler is installed right away. Until then the SDK ignores logs, events, traces and reports you send it. See When the launch waits for the app to become active.

The started: completion block says whether the launch was accepted (NO for a refused launch, such as an invalid token). It does not mean recording has started: a launch that waits for the app to become active reports YES at once. To act once recording is live, observe status or bugsee(didChangeStatus:) (see Lifecycle & status):

Objective-C
Swift

[Bugsee launchWithToken:@"<your_app_token>"
                options:nil
                started:^(BOOL accepted) {
    NSLog(@"Bugsee launch accepted: %d", accepted);
}];

// In your BugseeDelegate:
- (void)bugseeDidChangeStatus:(BugseeStatus)status {
    if (status == BugseeStatusLaunched) {
        // Recording is live
    }
}

Bugsee.launch(token: "<your_app_token>", options: nil) { accepted in
    print("Bugsee launch accepted: \(accepted)")
}

// In your BugseeDelegate:
func bugsee(didChangeStatus status: BugseeStatus) {
    if status == BugseeStatusLaunched {
        // Recording is live
    }
}

Debug builds

To build and enable Bugsee only in debug builds, keep it out of the release configuration and wrap every reference in your code with conditional compilation flags.

In an Xcode project, exclude the Bugsee framework from the release configuration in your build settings. Swift Package Manager cannot make a package dependency depend on the build configuration, so a Package.swift cannot do this for you.

Then wrap the call sites:

Objective-C
Swift

#ifdef DEBUG
@import Bugsee;
#endif

// ...

#ifdef DEBUG
[Bugsee launchWithToken:@"<your_app_token>"];
#endif

#if DEBUG
import Bugsee
#endif

// ...

#if DEBUG
Bugsee.launch(token: "<your_app_token>")
#endif

TestFlight builds

It makes sense in some cases to enable Bugsee on builds distributed through TestFlight but keep it disabled on builds distributed through the App Store. The receipt check below tells them apart at runtime. It is also true for a build installed on a device from Xcode.

warning

Application crashes can be intercepted by the system instead of Bugsee for builds installed via TestFlight. You can disable the "Share With App Developers" system option on test devices in Settings > Privacy & Security > Analytics & Improvements.

Objective-C
Swift

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...other initialization code

    if ([[[[NSBundle mainBundle] appStoreReceiptURL] lastPathComponent] isEqualToString:@"sandboxReceipt"]) {
        // TestFlight or a device build from Xcode, enable Bugsee!
        [Bugsee launchWithToken:@"<your_app_token>"];
    }

    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...other initialization code

    // TestFlight or a device build from Xcode
    let isRunningTestFlightBeta = Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt"
    if isRunningTestFlightBeta {
        Bugsee.launch(token: "<your_app_token>")
    }

    return true
}

Crash symbolication

Upload your app's dSYM files so crash stacks are symbolicated — follow the crash symbolication guide.

Found an issue, typo, or wrong statement on this page? Report it now →

Requirements​

Add the package​

Direct download​

Optional: in-app feedback​

Initialization​

Launching with options​

Knowing when the SDK is running​

Debug builds​

TestFlight builds​

Crash symbolication​