Crashes and errors

Download the instructions for the developer (TXT): crashes-developer-en.txt

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.

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 report. See also the Sending errors on different platforms section.

To reduce the app size, the code is optimized 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.

Learn more

• Crashes and errors report
• Android documentation

iOS: dSYM files

Crash information on iOS is sent in symbolicated 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 SDK, the helper command-line tool is included. For builds using fastlane, the upload plugin 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 to build the app:

1. Install the appmetrica fastlane plugin:

   fastlane add_plugin appmetrica
   

   Learn more about adding a plugin in the fastlane documentation.

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.

   Warning

   The 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.

   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
      

   Note

   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

helper -k <post-api-key> <file_path>

helper tool reference

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

& 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
• Apple documentation

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 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.

Sending errors on different platforms

• Android
• iOS
• Flutter
• React Native
• Unity