Uploading dSYM files on iOS

Information about crashes on iOS is sent in unsymbolicated crash logs. It's difficult to extract data for analysis from these crash logs. To analyze the crash logs, upload dSYM files to AppMetrica.

The AppMetrica SDK has a built-in command-line tool named helper for uploading dSYM files. To build an app based on fastlane, use the upload plugin. It helps you set up automatic uploading of dSYM files when building your app.

  1. Automatic uploading when building an app
  2. Uploading a missing dSYM file
  3. Helper tool reference

Automatic uploading when building an app

If Bitcode generation is enabled and you use fastlane to build your app:

  1. Install the appmetrica fastlane plugin:
    fastlane add_plugin appmetrica
    Copied to clipboard

    For more information about how to add the plugin, see fastlane docs.

  2. Add the following to the fastlane/Fastfile file:
    lane :release do
      # Your actions before.
      gym(
        workspace: "MyApp.xcworkspace",
        configuration: "Release",
        scheme: "MyApp",
        export_method: "app-store"        # Pass the correct export_method.
      )
      upload_symbols_to_appmetrica(post_api_key: "Post API key")
      # Your actions after.
    end
    Copied to clipboard

    You can get the Post API key in the Settings of AppMetrica. It's used to identify your app.

    Attention. Apps are built using the gym action with export enabled. If you build your app using Xcode, the app will be recompiled after you upload it to App Store Connect. In this case, you won't be able to use the dSYM files generated during the build.
If Bitcode generation is disabled
If Bitcode generation is disabled and you build your app using Xcode, you can add to the Build Phases a stage for uploading dSYM files via the helper.
Note. The helper tool is supported since the AppMetrica SDK version 3.8.0. It's in the SDK archive.
  1. Open the project in Xcode.
  2. In the project navigator, select the project file.
  3. In the Targets block, select your app.
  4. Open the Build Phases tab.
  5. Click + → New Run Script Phase.
  6. Add the following to the Type a script text field:
    if [ -d "${PODS_ROOT}/YandexMobileMetrica" ]; then
        HELPER_PATH=`find "${PODS_ROOT}/YandexMobileMetrica" -name "helper"`
        if [ -x $HELPER_PATH ]; then
            $HELPER_PATH auto --post-api-key="Post API key"&
        else
            echo "AppMetrica crash helper was not found"
        fi
    fi
    Copied to clipboard
    Note. The auto mode uses the CONFIGURATION environment variable. If the build is done with the Debug configuration, no dSYM files are uploaded.

    Helper tool reference.

Uploading a missing dSYM file

If a dSYM file wasn't uploaded when building an app, crash reports will display a warning about unsymbolicated crashes.

To symbolicate them, upload missing dSYM files. You can view the list of missing files on the Settings → Crashes page of your app in AppMetrica.

You can upload missing dSYM files:

  1. Install the appmetrica fastlane plugin:
    fastlane add_plugin appmetrica
    Copied to clipboard

    For more information about how to add the plugin, see fastlane docs.

  2. Add the following to the fastlane/Fastfile file:
    lane :refresh_dsyms do
      download_dsyms
      upload_symbols_to_appmetrica(post_api_key: "Post API key")
      clean_build_artifacts
    end
    Copied to clipboard
    In the download_dsyms action, you can specify the required app version and build number:
    ...
      download_dsyms(version: "1.0.0", build_number: "345")
    ...
    Learn more about the download_dsyms action in fastlane docs.

Helper tool reference

Note. The helper tool is supported since the AppMetrica SDK version 3.8.0. It's in the SDK archive.

Helper is a command-line tool that allows you to upload dSYM files to AppMetrica.

$ helper [auto] [-o | --package-output-path=<path>] [-v | --verbose]
         [--version] -k <post-api-key> | --post-api-key=<key> [file ...]

Parameters

auto
Auto upload mode. In this mode, the helper uses the following variables:
  • CONFIGURATION — Used to define the configuration. If the build is done with the Debug configuration, no dSYM files are uploaded.
  • DWARF_DSYM_FOLDER_PATH — Used to find dSYM files. It usually depends on the BUILT_PRODUCTS_DIR variable.
  • YMM_POST_API_KEYPost API key. If specified, you can use the short helper auto& command in the auto mode.
‑k

Post API key. You can get the Post API key in the Settings of AppMetrica. It's used to identify your app.

‑o

The path to the folder where temporary files are stored.

By default, the system folder is used.

‑v

Enables the display of additional information.

‑‑version

Outputs the version.

file

The list of dSYM files or folders where they are stored.

By default, the local working folder is used.

& lets you run the helper concurrently, without blocking the build of the entire project. Sample command:
helper auto --post-api-key="Post API key"&