Skip to main content

Uploading dSYMs

When applications are uploaded to the AppStore they are often stripped of symbols for security or space reasons. Much of the data our SDK collects relies on addresses, including our crash reports. If you choose not to upload your dSYM files, you will be required to manually symbolicate these addresses.

Important Note Starting on April 25, 2023 Apple will required all apps to be built with Xcode 14. Apple deprecated bitcode in Xcode 14. This means you may be unable to download dSYMs from Apple in the near future. We recommend that you setup automatic uploads. Apple Announcement

Automatic Uploads

Automatically uploading dSYM files is a good option for you if you are not using bitcode to distribute your application.

To enable automatic dSYM uploads, we will need to locate a number of items first:

  1. Your API key. This is a 5 character code used to start Embrace. It was provided to you when you registered for an Embrace account.
  2. Your API token. This is a longer character string. You can find it in the dashboard on the settings page, under the Tokens section.

Now, open the "Build Phases" tab in Xcode. We will be adding a new phase.

Use the "+" button on this tab to add a new "Run Script" phase. Name the phase "Embrace Symbol Uploads".

This phase is going to be calling Embrace's run.sh upload script. You can configure the phase to only run on builds you want symbols uploaded to Embrace for, and skip the step on internal only builds to save time.

The run.sh script is distributed alongside the Embrace.framework file. Depending on how you linked Embrace, this file will be in a different location. See the section relevant for your integration for how to call the run script.

Use this command format for CocoaPods integrations.

EMBRACE_ID=USE_YOUR_KEY EMBRACE_TOKEN=USE_YOUR_TOKEN "${PODS_ROOT}/EmbraceIO/run.sh"

Notice how the script's location is a reference to the CocoaPods installation folder.

info

In the examples above, notice how the environment variables for your key and token are on the same line as the call to the run.sh script. If the environment variables are on different lines, they will not be available when run.sh executes and the command will fail.

info

If your crashes are not being symbolicated due to dSYM files being missing, see the section on troubleshooting dSYM uploads in the FAQ.

Manual Uploads

If your app is using bitcode or a CI system that makes accessing or modifying the build phases impossible, you can still upload your dSYM files manually.

info

Apple is deprecating Bitcode Enabled submissions starting with Xcode 14, no longer accepts submissions with bitcode enabled and will remove the ability to build apps with bitcode enabled altogether on future Xcode releases. If your app still has bitcode enabled, it might be a good idea to disable it.

When applications are built with bitcode, it means the final binary and symbols only exist on Apple servers post-submission. As such you must download those symbols manually from Apple. You can do this from the Organizer window in Xcode.

Once you have the dSYMs on your computer, you can upload it to Embrace using our upload utility.

The upload utility is distributed with the Embrace SDK. See the section above on automatically uploading dSYMs to learn how to locate this file in your project. You will also need your API key and API token. You can upload dSYM and .zip files in the same command or use the upload tool on the Settings/Upload dSYM tab.

Run the upload tool and your dSYM will be sent to Embrace.

# Upload a single file
/EmbraceIO/upload --app $APP_KEY --token $API_TOKEN dsyms.zip

# Upload multiple files
/EmbraceIO/upload --app $APP_KEY --token $API_TOKEN --dsym my_dsym --dsym my_file.zip

This process can be scripted into your CI backend as well. Simply include the upload utility with your project's repo and call it from within the CI scripting system.


dSYM's are complicated, but ensuring that Embrace has them will make the data you collect much more useful. Please reach out if you have any trouble with this process.

In the next section, we'll learn how to keep Embrace updated.