The BugsplatMac OS X framework enables posting crash reports from Cocoa
applications to BugSplat. This allows for your team to process OS X crash reports with BugSplat.
- BugsplatMac supports OS X 10.7 and later.
- BugsplatMac supports x86_64 and Apple Silicon applications
BugsplatMac supports multiple methods for installing the library in a project.
Installation with CocoaPods
CocoaPods is a dependency manager for Objective-C,
simplifies the process of using 3rd-party libraries like BugsplatMac in your projects. You can install it
with the following command:
To integrate BugsplatMac into your Xcode project using CocoaPods, specify it
Then, run the following command:
The pod install command creates an xcworkspace file next to your application's xcodeproj file. Open the
xcworkspace file in lieu of the xcodeproj file to ensure BugsplatMac.framework is included in your build.
Installation with Carthage
Carthage is a decentralized
dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the
To integrate BugsplatMac into your Xcode project using Carthage, specify it in
carthage to build the framework and drag the built
BugsplatMac.framework into your Xcode project.
To use this library in your project manually you may:
- Download the latest release from https://github.com/BugSplatGit/BugsplatMac/releases
which is provided as a zip file
- Unzip the archive and add BugsplatMac.framework to your Xcode project
- Drag & drop
BugsplatMac.framework from your window in the
project in Xcode and move it to the desired location in the
- A popup will appear. Select
Create groups for any added folders and set the checkmark for
your target. Then click
- Configure the framework to be copied into your app bundle:
- Click on your project in the
Project Navigator (⌘+1).
- Click your target in the project editor.
- Click on the
Build Phases tab.
- Click the
Add Build Phase button at the bottom and choose
Add Copy Files.
- Click the disclosure triangle next to the new build phase.
Frameworks from the Destination list.
BugsplatMac from the Project Navigator left sidebar to the list in the new Copy
BugsplatMac requires a few configuration steps in order integrate the
with your Bugsplat account
- Add the following key to your app's Info.plist replacing DATABASE_NAME with your account name
- You must upload an xcarchive containing your app's binary and symbols to the Bugsplat server in order
symbolicate crash reports.
- Create a ~/.bugsplat.conf file to store your Bugsplat credentials
- Add the upload-archive.sh script located in Bugsplat.framework/Versions/A/Resources as an Archive
post-action in your build scheme. The script will be invoked when archiving completes which will
the xcarchive to Bugsplat for processing. You can view the script output in
/tmp/bugsplat-upload.log. To share amongst your team, mark the scheme as 'Shared'.
Crash Reporter UI Customization
- Custom banner image
- Bugsplat provides the ability to configure a custom image to be displayed in the crash reporter UI
branding purposes. The image view dimensions are 440x110 and will scale down proportionately. There
2 ways developers can provide an image:
- Set the image property directly on BugsplatStartupManager
- Provide an image named
bugsplat-logo in the main app bundle or asset calalog
NO in order to prevent the name and email fields
displaying in the crash reporter UI
- Bugsplat supports uploading attachments with crash reports. There's a delegate method provided by
BugsplatStartupManagerDelegate that can be implemented to provide an attachment to be
- Add "Other Linker Flags" build setting to embed Info.plist
-sectcreate __TEXT __info_plist "$(SRCROOT)/BugsplatTesterCLI/Info.plist"
@executable_path/ to "Runtime Search Paths" build setting
- Follow the main configuration steps listed above, however, use upload-archive-cl.sh for uploading
- Initialize as follows:
- Given the "Runtime Search Paths" setting change in step 2, be sure any 3rd party dependencies are
located in the same directory as the CLI program so they can be found at runtime.
We have provided BugsplatTester as a sample application for you to test
BugSplat. The quickest way to test BugSplat is to do the following:
Clone the BugsplatMac
repo and run the following:
- Open the BugsplatTester.xcworkspace file. Edit the current scheme and uncheck "Debug executable" in
Run section, close the scheme editor and run the application.
- Click the "crash" button when prompted.
- Click the run button a second time in Xcode. The BugSplat crash dialog will appear the next time the
- Fill out the crash dialog and submit the crash report.
- Visit BugSplat's Crashes
prompted for credentials enter user "firstname.lastname@example.org" and password "Flintstone". The crash you
from BugsplatTester should be at the top of the list of crashes.
- Click the link in the "Crash Id" column to view more details about your crash.
- You will notice there are no function names or line numbers, this is because you need to upload the
application's xcarchive. See step 2 in the "Configuration" section above for more information.
- Repeat this process with the executable from the xcarchive you created with BugsplatTester. To find
executable within the xcarchive, right click the xcarchive in finder and select "Show Package
The executable should be located in .../Products/Applications/. BugSplat will display function names
line numbers for all crashes posted from this executable.