# For the developer: collecting crashes and errors, debug files, and verification Article: Crashes and errors The developer connects failure collection and uploads files to decode them. This helps get a clear description of the problem and find its cause. #### How to configure collection Crash collection is provided in the AppMetrica SDK. Check the integration for your platform and the transfer settings. For custom error messages, the developer adds a call to the corresponding SDK method. For example, if the app handled a failed operation and showed the user a message, the developer can transfer the error for further analysis. Which situations to send is determined by the app team. Links to the Android, iOS, Flutter, React Native, and Unity methods are given in the [error sending instructions](#audit-about-crashes-and-errors-links). #### Files for decoding failures on Android and iOS Use files that match the app build in which the failure occurred. The requirements and upload methods for each platform are given below. ##### Android: mapping files and debug symbols AppMetrica allows you to collect information about native and Java crashes. You can analyze them in the [Crashes and errors](https://appmetrica.yandex.ru/docs/en/mobile-reports/crashes-and-errors) report. See also the [error sending instructions for platforms](#audit-about-crashes-and-errors-links). To reduce the app size, the code is [optimized](https://developer.android.com/studio/build/shrink-code) during the release build. If the code was shrunk and obfuscated during the Android app build, crash information is transferred in obfuscated form. To extract data for analysis from such crash logs, AppMetrica performs deobfuscation on the server side. To do this, upload mapping files or SO file debug symbols to AppMetrica: automatically during the app build or manually via the web interface. To send files, connect the [AppMetrica Gradle Plugin](https://appmetrica.yandex.ru/docs/en/sdk/android/analytics/android-gradle-plugin). Upload mapping files if you use [ProGuard](https://www.guardsquare.com/en/products/proguard/manual) or [R8](https://r8.googlesource.com/r8/). If you don't shrink or obfuscate the code, don't connect the plugin. ###### Learn more - [Crashes and errors report](https://appmetrica.yandex.ru/docs/en/mobile-reports/crashes-and-errors) - [Android documentation](https://developer.android.com/topic/performance/vitals/crash) ##### iOS: dSYM files Crash information on iOS is sent in [symbolicated](https://developer.apple.com/library/archive/technotes/tn2151/_index.html) form. It's difficult to extract data for analysis from such crash logs. To make crash logs analyzable, upload dSYM files to AppMetrica. To upload dSYM files to AppMetrica, the SDK includes the [helper](#dsym--helper) command-line tool. For builds using [fastlane](https://docs.fastlane.tools), the [upload plugin](https://github.com/yandexmobile/metrica-plugin-fastlane) is supported. With their help, you can configure automatic dSYM file upload during the app build. Please send dSYM files only for the apps you want to publish. ###### Automatic upload during the build Use [fastlane](https://docs.fastlane.tools) to build the app: 1. Install the `appmetrica` fastlane plugin: ``` fastlane add_plugin appmetrica ``` Learn more about adding a plugin in the [fastlane documentation](https://docs.fastlane.tools/plugins/using-plugins/#add-a-plugin-to-your-project). 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 ``` The Post API key can be obtained in the **Settings** section in AppMetrica. It's used to identify your app. The [gym](https://docs.fastlane.tools/actions/gym/#gym) action with export is used to build the app. If you build the app with Xcode, the app will be recompiled after uploading to App Store Connect. Then the dSYM files generated during the build can't be used. 3. Add the dSYM file upload step using the `helper` tool in Xcode. The `helper` tool is included in the AppMetrica SDK starting from version 3.8.0. It's located in the SDK archive. [helper tool reference](#dsym--helper). 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 the **+** button → **New Run Script Phase**. 6. In the **Type a script** text field, add: ``` if [ -d "${PODS_ROOT}/AppMetricaCrashes" ]; then HELPER_PATH=`find "${PODS_ROOT}/AppMetricaCrashes" -name "helper"` if [ -x "${HELPER_PATH}" ]; then "${HELPER_PATH}" auto --post-api-key="Post API key"& else echo "AppMetricaСrash helper was not found" fi fi ``` The `auto` mode uses the `CONFIGURATION` environment variable. If the build is built with the `Debug` configuration, dSYM files aren't uploaded. ###### Uploading a missing dSYM file If the dSYM file wasn't uploaded during the app build, the crash reports will show a warning about unsymbolicated crashes.  To symbolicate them, upload the missing dSYM files. The list of missing files can be viewed on the **Settings** → **Crashes** page of your app in AppMetrica. Missing dSYM files can be uploaded: Using fastlane Via the web interface Using helper 1. Install the `appmetrica` fastlane plugin: ``` fastlane add_plugin appmetrica ``` Learn more about adding a plugin in the [fastlane documentation](https://docs.fastlane.tools/plugins/using-plugins/#add-a-plugin-to-your-project). 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 ``` 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 the [fastlane](https://docs.fastlane.tools/actions/download_dsyms/) documentation. 1. Find the required archive with the dSYM file: 1. In the Xcode interface, click **Window** → **Organizer**. 2. In the **Archives** tab, select the required app version. 3. Click the **Download dSYM** button.  1. In the iTunes Connect interface, open the **Activity** page. 2. In the **All Builds** tab, select the required build number. 3. Click **Download dSYM**.  You can use the dSYM file that was generated during the build. 2. In the AppMetrica interface, go to the app settings from the left menu. 3. Open the **Crashes** → **iOS** tab. 4. Click the **Select file** button and upload a ZIP archive containing the `app.dSYM` or `app` directories. To upload using the plugin, you need to connect the AppMetrica SDK version 3.8.0 or higher. To upload missing dSYM files to AppMetrica, run the command in the terminal: ``` helper -k ``` `file_path` is a list of dSYM files or folders containing them. [helper tool reference](#dsym--helper). ###### helper tool reference The `helper` tool is included in the AppMetrica SDK starting from version 3.8.0. It's located 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=] [-v | --verbose] [--version] -k | --post-api-key= [file ...] ``` **Parameters** | Parameter | Description | | --- | --- | | `auto` | Automatic upload mode. In it, `helper` uses the following variables: - `CONFIGURATION` — used to determine the configuration. If the build is built with the `Debug` configuration, dSYM files aren't uploaded. - `DWARF_DSYM_FOLDER_PATH` — used to find dSYM files. It usually depends on the `BUILT_PRODUCTS_DIR` variable. - `AMA_POST_API_KEY` — *Post API key*. If specified, in automatic mode you can use the short command `helper auto&`. | | `-k` | Post API key. It can be obtained in the **Settings** section in AppMetrica. It's used to identify your app. | | `-o` | Path to the folder where temporary files are stored. The system folder is used by default. | | `-v` | Enables the display of additional information. | | `--version` | Outputs the version. | | `file` | List of dSYM files or folders containing them. The local working folder is used by default. | `&` allows you to run `helper` in parallel without blocking the build of the entire project. Example command: ``` helper auto --post-api-key="Post API key"& ``` ###### Learn more - [Crashes and errors report](https://appmetrica.yandex.ru/docs/en/mobile-reports/crashes-and-errors) - [Apple documentation](https://developer.apple.com/library/archive/technotes/tn2151/_index.html) The Post API key can be obtained in the **Settings** section in AppMetrica. It's used to identify your app. #### How to check the result 1. In the test environment, reproduce a controlled error or failure. 2. Open the [Crashes and errors](https://appmetrica.yandex.ru/docs/en/mobile-reports/crashes-and-errors) report and find the data of the test app version. 3. Check the message, device, and call stack — the sequence of functions related to the failure. 4. If the stack isn't readable, check for debug files specifically for this build. Crashes are grouped by call stack; error grouping depends on the sending method. Details — in the [crashes and errors documentation](#crashes-developer). #### Sending errors on different platforms - [Android](https://appmetrica.yandex.ru/docs/en/sdk/android/analytics/android-operations#send-report-error) - [iOS](https://appmetrica.yandex.ru/docs/en/sdk/ios/analytics/ios-operations#send-report-error) - [Flutter](https://appmetrica.yandex.ru/docs/en/sdk/flutter/analytics/flutter-operations#send-report-error) - [React Native](https://appmetrica.yandex.ru/docs/en/sdk/react-native/analytics/react-native-operations#send-report-error) - [Unity](https://appmetrica.yandex.ru/docs/en/sdk/unity/analytics/unity-operations#send-report-error)