How to collect bug reports from a macOS app (Swift)

The short answer: put a Report an Issue… item in your app's Help menu that collects the user's description and attaches logs, versions and a screenshot for them. Then make sure you can reply. This guide shows how to do that in a Swift or SwiftUI Mac app in about ten minutes.

What makes a Mac bug report useful?

Most reports from users say "it doesn't work". To act on one, you need:

The app and macOS version, so you can tell an old build from a new bug.
The tail of your log file, covering the minutes before the problem.
A screenshot of the window, because users describe UI differently than you do.
A way to ask a follow-up question, since the first report is rarely enough.

Asking users to find and attach these themselves doesn't work. The report tool has to gather them when the user chooses "Report an Issue…".

Step 1: Create an app in StareGlare

Step 2: Add the SnagReporter Swift package

In Xcode, choose File → Add Package Dependencies…, paste https://github.com/gorgekara/snagfrog-swift and add the SnagReporter library to your app target.

Step 3: Add the menu item

Call this once at launch, for example in applicationDidFinishLaunching:

import SnagReporter

let snag = SnagReporter(
    appSlug: "your-app",
    publicKey: "snag_pk_…",
    baseURL: URL(string: "https://stareglare.com")!
)

// Adds "Report an Issue…" to the Help menu
NSApp.helpMenu?.addItem(snag.menuItem(logFiles: { [logFileURL] }))

The dashboard's Install tab shows this snippet with your real app slug and key. Pass the log files you already write; SnagReporter sends only their tail. You can also call snag.report(logFiles:) from your own button or a SwiftUI command.

Step 4: Send a test report and reply to it

Choose Help → Report an Issue…, write a sentence and send it. The report shows up in your inbox with the logs, versions and screenshot attached. Reply from the inbox: if the reporter left an email, they get your answer by email, and their reply threads back into the same report.

Step 5: Ask for a report after a crash

If macOS wrote a crash report for your app in the last 7 days, report() attaches it and the report is marked as a crash in your inbox. To ask people right after a crash, call this once at launch:

Task { await snag.offerReportAfterCrash(logFiles: [logFileURL]) }

After a crash, the next launch shows "YourApp quit unexpectedly. Would you like to send a report?" once. With this call nothing is sent on its own: the person chooses to send. Apps in the App Sandbox (Mac App Store builds) can't read macOS crash reports, so there this does nothing and reports work as usual. Apple describes where crash reports are kept and how to read one in Acquiring crash reports and diagnostic logs.

Bug reports vs crash reports

Crash reporters collect every crash without the user doing anything. A bug report tool catches what isn't a crash, in the user's own words, and lets you answer. They complement each other. If you only add one to a small app, add the one that lets users talk to you.

Questions

What is the simplest way to collect bug reports from a Mac app?

Add a "Report an Issue…" item to the Help menu that opens a short form and attaches your log files, the macOS and app version, and a window screenshot automatically. With StareGlare this is the SnagReporter Swift package and about six lines of code.

Do I need a crash reporter as well?

A crash reporter such as Sentry or Crashlytics collects every crash, symbolicates it and tracks it across releases. StareGlare is built for the reports people choose to send: wrong behaviour, confusing UI, feature requests, and, after a crash, a report with the macOS crash log attached. Since version 0.5.0 the package can also send a crash on its own if you turn that on (it is off by default), grouped in the Errors tab, without symbolication. Many indie apps use both.

Does this work for apps outside the Mac App Store?

Yes. SnagReporter only needs network access, so it works in sandboxed App Store apps (with the outgoing connections entitlement) and in apps you distribute yourself.

Can I reply to the person who reported the bug?

Yes. If they leave an email address, your reply from the StareGlare inbox reaches them by email, their answer threads back into the same report, and they get a private page to follow its status.

Related guides

All 6 guides, from the first report to the fix.