iOS SDK

What the iOS SDK does #

The TesterBuddy iOS SDK is a Swift package you embed in the app you're testing. It captures diagnostic data from real testers on real devices and sends it to your TesterBuddy dashboard — without requiring any changes to your app's UI.

Installation #

The SDK is distributed via Swift Package Manager. No CocoaPods, no Carthage, no extra setup.

1. 1
   File → Add Package Dependencies in Xcode

   Paste the repository URL:

https://github.com/DavidTereba/testerbuddy-ios-sdk

1. 2
   Select version 1.2.0 or later

   Choose "Up to Next Major Version" to receive future updates automatically.
2. 3
   Add TesterBuddy to your target

   Select your app target and tick the TesterBuddy library. Click Add Package.

Open your app in TesterBuddy → tap iOS SDK Setup on the app detail screen. Your SDK key is shown there and can be copied directly.

Quick Start #

Call configure as early as possible — in App.init() or application(_:didFinishLaunchingWithOptions:). That's all you need for crash reporting, shake-to-report, and auto tester identification.

import TesterBuddy

@main
struct MyApp: App {
    init() {
        TesterBuddy.configure(apiKey: "your_sdk_key")
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

TesterBuddy.configure(
    apiKey: "your_sdk_key",
    userId: nil,                    // set tester ID manually (optional)
    enableANRDetection: true,       // detect frozen main thread (≥ 5 s)
    enableNetworkMonitoring: false, // intercept failed URLSession requests (opt-in)
    enableSessionTracking: true,    // track launch count & session duration
    enableAnnouncements: true       // show developer banners inside the app
)

Crash Reporting #

Crash reporting is enabled automatically when you call configure. The SDK installs an NSUncaughtExceptionHandler that captures uncaught exceptions, saves them to disk, and sends them to TesterBuddy on the next launch — so data is never lost even if the device was offline when the crash occurred.

The SDK chain-calls any previously installed exception handler, so it works alongside Firebase Crashlytics, Sentry, or any other crash reporter you already use. No conflicts.

• Exception name and reason
• Call stack (symbolicated where available)
• Device model, iOS version, app version
• Current screen name (if set via Screen Tracking)
• Tester identity (if identified)

Shake to Report #

When a tester shakes their device, a feedback sheet slides up automatically. No view modifications needed — the SDK handles everything after configure().

• A screenshot of the current screen, captured at the moment of the shake
• A type selector: Bug, Idea, or Other
• A description field
• A Send button

The report is sent to your TesterBuddy dashboard immediately and posted as a message to the tester's individual feedback thread. You get a push notification — same as any other message from a tester.

ANR Detection #

ANR (Application Not Responding) detection monitors your main thread with a background watchdog. If the main thread is unresponsive for 5 seconds or more, an anr event is logged with the duration and current screen name.

Enabled by default. To disable:

TesterBuddy.configure(apiKey: "...", enableANRDetection: false)

Network Monitoring #

Network monitoring is opt-in. When enabled, the SDK intercepts URLSession.shared and default-configuration sessions, and reports failed connections and HTTP 4xx/5xx responses as network_error events.

TesterBuddy.configure(apiKey: "...", enableNetworkMonitoring: true)

• Requests through URLSession.shared and .default configuration — covered automatically
• Sessions with custom configurations — not intercepted automatically
• Manual logging always available (see below)

You can log network errors manually at any time, even with automatic monitoring disabled:

TesterBuddy.logNetworkError(url: "https://api.example.com/items", statusCode: 503)

Session Tracking #

Session tracking records launch count, session duration, and whether the previous session ended in a crash. A session event is sent on each launch and when the app goes to background.

Events are visible in the dashboard under the Custom events filter. Enabled by default. To disable:

TesterBuddy.configure(apiKey: "...", enableSessionTracking: false)

Developer Announcements #

Send a message from the TesterBuddy dashboard directly into your app. It appears as a non-blocking banner at the top of the screen for any tester who opens the app.

• Each announcement is shown once per device — no repeated nags
• Optional expiry (e.g. auto-expire after 24 hours)
• Tap to dismiss, or auto-dismisses after 8 seconds
• Created from TesterBuddy app → App detail → Announcements section

Enabled by default. To disable:

TesterBuddy.configure(apiKey: "...", enableAnnouncements: false)

Offline Queue #

Events captured while the device is offline (no network, server unreachable) are stored in the app's cache directory and automatically flushed on the next successful send. No setup required — it's transparent for all event types.

• Capacity: 500 events (oldest dropped first when full)
• Storage: app's caches/ directory — never iCloud synced, never backed up
• Flush: automatic on next successful network request

Manual Logging #

Log any custom event or network error directly from your code:

// Simple event
TesterBuddy.log(message: "User completed onboarding")

// Event with metadata
TesterBuddy.log(message: "Feature flag evaluated", metadata: [
    "flag":   "new_checkout",
    "result": "enabled"
])

// Network error (useful when automatic monitoring is off)
TesterBuddy.logNetworkError(url: "https://api.example.com/data", statusCode: 503)

Custom events appear in the dashboard under the Custom filter alongside session events.

Tester Identification #

Identifying testers links every crash, ANR, and custom event to a specific person in your TesterBuddy dashboard. You can see exactly who experienced each issue.

When a tester taps Start Testing in the TesterBuddy app, a one-time token is placed on their clipboard. On the first launch of your app, the SDK reads and exchanges the token automatically — no manual code needed.

If your app has its own authentication, you can identify testers using their TesterBuddy ID after sign-in:

TesterBuddy.setUserId(currentUser.tbTesterId)  // on sign-in
TesterBuddy.setUserId(nil)                     // on sign-out

Screen Tracking #

Set the current screen name so all events (crashes, ANRs, custom logs) include context about where in the app they happened:

.onAppear {
    TesterBuddy.setScreen("CheckoutView")
}

The screen name appears in every event's detail view in the dashboard.

Privacy & App Store #

The SDK ships with a PrivacyInfo.xcprivacy manifest required by Apple since May 2024. You don't need to create one yourself — it's bundled in the package.

• No IDFA or ATT usage — no tracking consent prompt required
• No keylogger, no view content reading, no microphone or camera access
• No data sold or shared beyond testerbuddy.app

When submitting your app to the App Store, declare in App Privacy:

• Crash Data → App Functionality → Not linked to user
• Performance Data → App Functionality → Not linked to user
• If you use setUserId(), also add: User ID → Developer's App Functionality → Linked to user