Crash symbolication

Bugsee is able to properly process and symbolicate crash reports that are uploaded from your users. Even if your binary has its symbol stripped, Bugsee will do wonders guessing the right symbols. In some cases it might be enough to root cause the problem, however best results will be achieved when Bugsee can match a crash report with a symbol file (dSYM) of crashed build.

Bugsee can automatically upload dSYM files during the build phase. The system is smart enough to match the right dSYM to a crash report.

Auto dSYM upload

Edit your scheme by going to Product->Scheme->Edit Scheme.

  • Add an extra "Run Script" build phase to "Post-actions" stage of your scheme

Build phase

Don't forget to select proper scheme for "Provide build settings from"! Otherwise, scrpt will not be provided with proper inputs and will not be able to collect and upload dSYMs.
  • Paste the following script into it and don't forget to change your_app_token with the one you use for initializing the SDK
SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'BugseeAgent' | head -1)
if [ ! "${SCRIPT_SRC}" ]; then
    echo "Error: BugseeAgent script not found !!!"
    echo "If you link Bugsee.framework from outside the project folder, please copy the script"
    echo "into your main project directory or manually update SCRIPT_SRC variable with the right path"
    exit 1
/usr/bin/python "${SCRIPT_SRC}" <your_app_token> >> /tmp/BugseeAgent.txt

The script above finds the BugseeAgent helper utility within your project folder (location may vary). For optimization purposes you can modify the script with the direct link to BugseeAgent in your particular folder structure.

Note that for platforms like React Native, BugseeAgent is located in node_modules directory which is one-level up from the project directory. Don't forget to reflect that in script above by appending "/../" to the $PROJECT_DIR variable.

Debug builds

You must also make sure that dSYM files are being created in debug configuration as well, as usually that is not the case:

dSYM generation

In case you are are using CocoaPods frameworks with use_frameworks! attribute enabled, you might want to add the following post install hook to the end of your Podfile to make sure dSYM for all the frameworks are being generated as well:

#...end of Podfile...
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['DEBUG_INFORMATION_FORMAT'] = 'dwarf-with-dsym'

Manual dSYM upload

In some cases you might need to upload dSYM files manually. Bugsee accepts .zip files with one or multiple dSYM files inside. Once you have located the files and compressed them into an archive, click on the "Manual upload" button within Bugsee and either drag your files over the dialog or click on it to open the file browser:

Manual upload

Once a dSYM file is uploaded manually, we are going to re-process old issues related to that specific build, the process might take some time, usually several minutes.

Bitcode enabled builds

When you submit Bitcode-enabled builds to Apple Appstore, the dSYM files generated locally in your Mac are not going to be helpful in symbolication process due to the fact Apple is recompiling your apps before distributing them to the users. Proper dSYM should be obtained from Apple and the uploaded to Bugsee to process your crash reports. Follow the steps below to obtain the dSYM files:

Downloading dSYM files using XCode

  1. Go to your Xcode Organizer, point to the build you submitted and click on the “Download symbols"

    Download symbols

  2. Right click on the build and select “Show in Finder”:

    Download symbols

  3. Once in Finder, right click on the package and select on “Show package contents”

    Download symbols

  4. Inside the dSYM folder you should find several files which correspond to symbol files for different architectures. Compress them and upload them following the procedure for manual dSYM uploading.

    Download symbols

Downloading dSYM files using iTunes Connect

  1. Locate your build in iTunes connect and click on the Download dSYM link

    iTunes Connect

  2. Upload the zip file you just downloaded directly to Bugsee by following the procedure for manual dSYM uploading. If your build has multiple architectures and/or multiple binary files, all the dSYM files are already included in the zip file and will be processed automatically.

Fastlane dSYM upload

Bugsee supports fastlane for uploading dSYM files by providing a fastlane plugin with upload_symbols_to_bugsee action.

Add bugsee fastlane to your project:

fastlane add_plugin bugsee

For uploading symbols during build(gym) (non-bitcode case):

lane :mybuildlane do
        # your settings for the build
        app_token: "<your_app_token>",

For refreshing dSYM files from iTunes connect (bit-code case):

lane :refresh_dsyms do
        build_number: "1819" # optional, otherwise it will download dSYM for all builds
  ) # Download dSYM files from iTC
        app_token: "<your_app_token>",
  clean_build_artifacts           # Delete the local dSYM files