Uploading dSYMs

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.

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.

Build Phase

Xcode opened to the 'Build Phases' tab. Note the '+' button in the upper middle for adding new phases

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.

Carthage linking requires a download of a Carthage Support zip file from this location.

Place those files in your project where you can easily find and reference them later. The path you put these files in will be the path used by the dSYM upload phase. The zip file contains the run.sh script, so modify the path below to match your location.

EMBRACE_ID=USE_YOUR_KEY EMBRACE_TOKEN=USE_YOUR_TOKEN "$(SRCROOT)/my/path/EmbraceIO/run.sh"

For Manual linking, the command looks similar to the CocoaPods version but the location has changed.

EMBRACE_ID=USE_YOUR_KEY EMBRACE_TOKEN=USE_YOUR_TOKEN "$(SRCROOT)/third_party/EmbraceIO/run.sh"

In this version we’re referencing the Embrace folder inside our third_party folder at the root of our project.

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. This is important, if the environment variables are not available when run.sh executes, the command will fail.

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.

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.

Organizer window in Xcode

The organizer window will allow you to download the dSYM files from Apple

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.

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

/EmbraceIO/upload -app $APP_KEY -token $API_TOKEN dsyms.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.

Keeping Embrace Up To Date