bugscreen
docsios

iOS SDK

v1.3.0

Integrate BugScreen into your iOS app in minutes. Swift, SwiftUI, UIKit, SPM.

Installation

Swift Package Manager

In Xcode, choose File → Add Package Dependencies… and enter the repository URL:

text
https://github.com/bugscreenapp/bugscreen-ios

Or add it to your Package.swift:

Package.swift
swift
dependencies: [
    .package(url: "https://github.com/bugscreenapp/bugscreen-ios", from: "1.3.0")
]

CocoaPods

Add BugScreenSDK to your Podfile:

Podfile
ruby
pod 'BugScreenSDK', '~> 1.3'

Then run pod install.

Requires iOS 15.0+ and Swift 5.9+.

Setup

BugScreen is for dev/QA — gate BugScreenSDK.configure(...) so it doesn't run for end users. Pick one:

#if DEBUG guard

SDK still linked into the binary, but dead-stripped from release builds.

MyApp.swift
swift
import SwiftUI

#if DEBUG
import BugScreenSDK
#endif

@main
struct MyApp: App {
    init() {
#if DEBUG
        BugScreenSDK.configure(
            apiKey: "fb_your_api_key_here",
            enableScreenshotDetection: true
        )
#endif
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
AppDelegate.swift
swift
import UIKit

#if DEBUG
import BugScreenSDK
#endif

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
#if DEBUG
        BugScreenSDK.configure(
            apiKey: "fb_your_api_key_here",
            enableScreenshotDetection: true
        )
#endif
        return true
    }
}

Tester-flag guard

Runs on production builds for users you flag as testers — useful for dogfooding.

MyApp.swift
swift
import SwiftUI
import BugScreenSDK

@main
struct MyApp: App {
    init() {
        // currentUser.isTester is pseudocode — replace with your tester signal.
        if currentUser.isTester {
            BugScreenSDK.configure(
                apiKey: "fb_your_api_key_here",
                enableScreenshotDetection: true
            )
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Photo Library Access (Recommended)

Add this to your Info.plist so BugScreen can auto-attach the screenshot the user just took, and so users can pick screenshots manually:

xml
<key>NSPhotoLibraryUsageDescription</key>
<string>Attach screenshots to bug reports to help us fix issues faster</string>
Auto-attach: When a screenshot is detected, BugScreen renders a snapshot of the current window and pre-attaches it immediately. If the user grants photo library access, BugScreen also looks up the actual screenshot from Photos and swaps it in. Without permission, the window snapshot remains attached.

Usage

Automatic screenshot detection

When users take a screenshot, BugScreen automatically presents the bug report UI. No additional code required. Reporters can attach up to four screenshots to a single report from the in-app sheet.

Manual triggering (SwiftUI)

Present the bug report screen programmatically:

swift
Button("Report Bug") {
    BugScreenSDK.presentBugReport()
}

// With pre-attached screenshot
Button("Report with Screenshot") {
    BugScreenSDK.presentBugReport(screenshot: myImage)
}

Manual triggering (UIKit)

swift
@IBAction func reportBugTapped(_ sender: UIButton) {
    BugScreenSDK.presentBugReport(from: self)
}

// With screenshot
BugScreenSDK.presentBugReport(
    from: self,
    screenshot: myImage
)

Logging

Add context to bug reports with application logs:

swift
BugScreenSDK.log("Detailed debug info", level: .verbose)
BugScreenSDK.log("Debug message", level: .debug)
BugScreenSDK.log("User tapped checkout button", level: .info)
BugScreenSDK.log("Network request took longer than expected", level: .warning)
BugScreenSDK.log("Payment failed: \(error.localizedDescription)", level: .error)

Logs are automatically included with every bug report. The SDK maintains a 1 MB circular buffer of the most recent logs.

Custom data

Attach arbitrary key/value pairs to every subsequent bug report:

swift
// Replace the whole map:
BugScreenSDK.setCustomData([
    "env": "staging",
    "buildType": "debug",
    "userTier": "pro",
])

// Set or remove a single key:
BugScreenSDK.setCustomData(key: "userId", value: "abc-123")
BugScreenSDK.removeCustomData(key: "userId")

// Merge a map without replacing existing keys:
BugScreenSDK.addCustomData(["plan": "pro", "region": "eu"])

// Remove all custom data:
BugScreenSDK.clearCustomData()

Call any time after configure() from the main actor. The values are read when the bug report screen opens and appear in the report's metadata.

Configuration

OptionDefaultDescription
apiKey: StringRequiredYour API key from the BugScreen console (must start with "fb_")
enableScreenshotDetection: BooltrueAuto-detect screenshots and present bug report UI
debug: BoolfalseEnable SDK debug behavior (gate with #if DEBUG)

What gets collected?

BugScreen automatically collects this information with each report:

  • •Device model (e.g. Apple iPhone16,1)
  • •iOS version
  • •App version & build number
  • •Bundle identifier
  • •Screen size (points and pixels) & scale
  • •Memory (total & available)
  • •Device locale

Start shipping bug reports

Create an account to start shipping bug reports from your app.

Get started