macOS
Introduction 👋
BugSplat.xcframework enables posting crash reports from iOS, macOS, and Mac Catalyst applications to BugSplat. Visit bugsplat.com for more information and to sign up for an account.
Requirements 📋
BugSplat for iOS supports iOS 13 and later.
BugSplat for macOS supports macOS 10.13 and later.
Integration 🏗️
BugSplat supports multiple methods for installing the xcfamework in a project.
Swift Package Manager (SPM)
Add the following URL to your project's Additional Package Dependencies
:
Manual Setup
To manually install BugSplat.xcframework in your project:
Download the latest release from the Releases page. The release will contain a zip file with the xcframework.
Unzip the archive.
In Xcode, select your app target, then go to the General tab, scroll down to Framework, Libraries, and Embedded Content, then click the "+" and navigate to locate the unzipped BugSplat.xcframework. Once added, select Embed & Sign.
Usage 🧑💻
Configuration
BugSplat requires a few Xcode configuration steps to integrate the xcframework with your BugSplat account.
Add the following case-sensitive key to your app's Info.plist
replacing DATABASE_NAME
with your customer-specific BugSplat database name.
For macOS apps, you must enable Outgoing network connections (client)
in the Signing & Capabilities of the Target.
Symbol Upload
To symbolicate crash reports, you must upload your app's dSYM
files to the BugSplat server. There are scripts to help with this.
Download BugSplat's cross-platform tool, symbol-upload-macos for Apple Silicon by entering the following command in your terminal.
Alternatively, you can download the Intel version via the following command.
Make symbol-upload-macos
executable
Several options exist to integrate symbol-upload-macos
into the app build process.
Create an Xcode build-phase script to upload dSYM files after every build. See example script Symbol_Upload_Examples/Build-Phase-symbol-upload.sh
Create an Xcode Archive post-action script in the target's Build Scheme in order to upload dSYM files after the app is archived and ready for submission to TestFlight or the App Store. See example script Symbol_Upload_Examples/Archive-post-action-upload.sh
Manually upload an
xcarchive
ordSYM
file generated by Xcode via BugSplat's Versions page.
For the build-phase script to create dSYM files, change Build Settings DEBUG_INFORMATION_FORMAT
from DWARF
to DWARF with dSYM File
. See inline notes within each script for modifications to Xcode Build Settings required for each script to work.
Please refer to our documentation to learn more about how to use symbol-upload-macos
.
Initialization
Several iOS and macOS test app examples are included within the Example_Apps folder to show how simple and quickly BugSplat can be integrated into an app, and ready to submit crash reports.
You can instantiate BugSplat by following the language-specific examples below.
Swift (UIKit)
Swift (SwiftUI)
Obj-C
Attributes
BugSplat supports custom attributes that can be added to a crash report. These attributes are searchable in the BugSplat dashboard.
Please see the framework-specific sample applications for more examples demonstrating how to use attributes.
Crash Reporter Customization
There are several ways to customize your BugSplat crash reporter.
Custom Banner Image
BugSplat for macOS provides the ability to configure a custom image to be displayed in the crash reporter UI for branding purposes. The image view dimensions are 440x110 and will scale down proportionately. There are 2 ways developers can provide an image:
Set the image property directly on BugSplat
Provide an image named
bugsplat-logo
in the main app bundle or asset catalog
User Details
Set
askUserDetails
toNO
to prevent the name and email fields from displaying in the crash reporter UI. Defaults toYES
.
Auto Submit
By default, BugSplat will auto-submit crash reports for iOS and prompt the end user to submit a crash report for macOS. This default can be changed using a BugSplat property autoSubmitCrashReport. Set
autoSubmitCrashReport
toYES
in order to send crash reports to the server automatically without presenting the crash reporter dialogue.
Persist User Details
Set
persistUserDetails
toYES
to save and restore the user's name and email when presenting the crash reporter dialogue. Defaults toNO
.
Expiration Time
Set
expirationTimeInterval
to a desired value (in seconds) whereby if the difference in time between when the crash occurred and the next launch is greater than the set expiration time, auto-send the report without presenting the crash reporter dialogue. Defaults to-1
, which represents no expiration.
Attachments
Bugsplat supports uploading attachments with crash reports. There's a delegate method provided by BugSplatDelegate
that can be implemented to provide attachments to be uploaded.
Bitcode
Bitcode was introduced by Apple to allow apps sent to the App Store to be recompiled by Apple itself and apply the latest optimization. Bitcode has now been officially deprecated by Apple and should be removed or disabled. If Bitcode is enabled, the symbols generated for your app in the store will be different than the ones from your own build system. We recommend that you disable bitcode in order for BugSplat to reliably symbolicate crash reports. Disabling bitcode significantly simplifies symbols management and currently doesn't have any known downsides for iOS apps.
Localization
For macOS, the BugSplat crash dialogue can be localized and supports 8 languages out of the box.
English
Finnish
French
German
Italian
Japanese
Norwegian
Swedish
Additional languages may be supported by adding the language bundle and strings file to BugSplat.xcframework/macos-arm64_x86_64/BugSplatMac.framework/Versions/A/Frameworks/HockeySDK.framework/Resources/
Sample Applications 🧑🏫
Example_Apps
includes several iOS and macOS BugSplat Test apps. Integrating BugSpat only requires the xcframework, and a few lines of code.
Clone the bugsplat-apple repo.
Open an example Xcode project from
Example_Apps
. For iOS, set the destination to be your iOS device. After running from Xcode, stop the process and relaunch from the iOS device directly.Once the app launches, click the "crash" button when prompted.
Relaunch the app on the iOS device. At this point a crash report should be submitted to bugsplat.com
Visit BugSplat's Crashes page. When prompted for credentials, enter user
fred@bugsplat.com
and passwordFlintstone
. The crash you posted from BugSplatTester should be at the top of the list of crashes.Click the "Crash ID" link to view more details about your crash.
Last updated
Was this helpful?