docs: improve symbolication and dSYM upload accuracy across platforms (#738)

* Improve symbolication and dSYM upload docs accuracy across platforms

- iOS: Add retroactive symbolication note, prerequisites section (dwarf-with-dsym),
  debug mode docs (EMBRACE_DEBUG_DSYM=1), improved troubleshooting
- iOS CI: Fix CLI flag syntax from -app/-token to --app/--token
- Android: Add mapping upload configuration info to crash reporting page
- Android: Document embrace.disableMappingFileUpload Gradle property
- Flutter: Add SPM instructions and DEBUG_INFORMATION_FORMAT requirement for dSYM upload
- React Native 5x: Fix source map path to use embrace-assets directory
- Product: Add retroactive symbolication note to dSYM symbols settings page

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update crash-reporting.md

* Revert RN 5x source map path change — 5.x SDK used the old path

The embrace-assets subdirectory was introduced in 6.x. The 5.x SDK
(verified at tag v5.2.0 in scripts/util/ios.ts) used
$CONFIGURATION_BUILD_DIR/main.jsbundle.map without the subdirectory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nelsitoPuglisi

docs/android/configuration/embrace-gradle-plugin.md

@@ -128,6 +128,18 @@ Whether the Embrace Gradle Plugin should report telemetry on its own performance
 
 Whether the Embrace Gradle Plugin should fail the build if it encounters an error during a HTTP request. Defaults to true.
 
+### Gradle Properties
+
+The following properties can be set in your `gradle.properties` file:
+
+#### embrace.disableMappingFileUpload
+
+Set to `true` to disable the automatic upload of ProGuard/R8 mapping files and NDK symbol files. This is useful when using Embrace solely as an OTel exporter without sending data to Embrace's backend. Example:
+
+```properties
+embrace.disableMappingFileUpload=true
+```
+
 #### bytecodeInstrumentation.enabled
 
 Global flag that overrides all others & decides whether Embrace should perform any bytecode instrumentation. Defaults to true.

docs/android/integration-advanced/crash-reporting.md

@@ -32,3 +32,12 @@ The Embrace SDK does not automatically capture NDK crash reports. To enable NDK
 
 If you have obfuscated your application with ProGuard, DexGuard, or R8, the captured crashes will contain obfuscated method names. The Embrace
 Gradle plugin will automatically upload mapping files at build time to get you human-readable stacktraces from production.
+
+:::info Configuration
+Mapping file uploads are skipped for debuggable builds or when API credentials are missing. You can control upload behavior with these Gradle properties:
+
+- `embrace.disableMappingFileUpload=true` in `gradle.properties` to disable mapping file uploads entirely
+- `embrace.failBuildOnUploadErrors` (default: `true`) in the `embrace` DSL block to control whether upload failures break the build
+
+For more details, see the [Embrace Gradle Plugin configuration](/android/configuration/embrace-gradle-plugin).
+:::

docs/flutter/integration/index.md

@@ -48,15 +48,25 @@ import EmbraceCrash
 ### Upload symbol files
 
 :::info
-Embrace uploads your application's dSYM symbol files using a script bundled with the Embrace iOS SDK. This makes stacktraces from crashes human-readable.
+Embrace requires your application's dSYM symbol files to make stacktraces from crashes human-readable.
 :::
 
-On the Xcode **Build Phases** tab, add a new run script. You can find your 5-character app ID and API token in the Embrace dashboard:
+On the Xcode **Build Phases** tab, add a new run script. You can find your 5-character app ID and API token in the Embrace dashboard.
+
+If you are using CocoaPods, the `run.sh` script is bundled with the SDK:
 
 ```shell-session
 EMBRACE_ID={YOUR_APP_ID} EMBRACE_TOKEN={YOUR_API_TOKEN} "${PODS_ROOT}/EmbraceIO/run.sh"
 ```
 
+If you are using Swift Package Manager, you must download the support utility from https://downloads.embrace.io/embrace_support.zip, extract it, and place the scripts in your project:
+
+```shell-session
+EMBRACE_ID={YOUR_APP_ID} EMBRACE_TOKEN={YOUR_API_TOKEN} "${SRCROOT}/path/to/your/run.sh"
+```
+
+Also ensure that `DEBUG_INFORMATION_FORMAT` is set to `DWARF with dSYM File` in your Build Settings. For more details, see the [iOS dSYM Upload guide](/ios/6x/getting-started/dsym-upload).
+
 ## Android setup
 
 In the root-level `build.gradle` file, add the `embrace-swazzler` dependency:

docs/ios/6x/getting-started/dsym-upload.md

@@ -12,6 +12,22 @@ When applications are uploaded to the App Store they are often stripped of symbo
 Starting on April 25, 2023 Apple requires 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](https://developer.apple.com/news/?id=2ygwqlzd)
 :::
 
+:::info Retroactive Symbolication
+Embrace performs symbolication server-side and retroactively. If a dSYM is uploaded after a crash has already been received, Embrace will automatically re-symbolicate older crashes when the matching dSYM arrives. This means you don't lose crash data if dSYMs are uploaded later.
+:::
+
+## Prerequisites
+
+Before setting up dSYM uploads, ensure your Xcode project is configured to generate dSYM files:
+
+1. Select your project in the Project Navigator
+2. Select the appropriate target
+3. Go to **Build Settings** > **All**
+4. Search for **Debug Information Format**
+5. Set the value to **DWARF with dSYM File** (`dwarf-with-dsym`) for both Debug and Release configurations
+
+If this setting is set to `dwarf` (without dSYM), no dSYM files will be generated and the upload script will skip the upload with a warning message.
+
 ## Automatic Uploads
 
 Automatically uploading dSYM files is the recommended approach for symbolication. This ensures that crash reports are properly symbolicated without manual intervention.
@@ -95,11 +111,21 @@ If you are using GitHub Actions, you may instead use [embrace-io/action-symbol-u
 
 If your crashes are not being symbolicated:
 
-1. Verify that dSYM files are being generated in your build settings
+1. Verify that `DEBUG_INFORMATION_FORMAT` is set to `dwarf-with-dsym` in your build settings
 2. Check that the upload script is running successfully in your build logs
 3. Ensure your App ID and API Token are correct
 4. Verify that the dSYM files match the build that crashed
 
+### Debug Mode
+
+The upload script runs in the background by default, which means upload logs appear in your system logs rather than in Xcode's build output. If you need to troubleshoot upload issues, enable debug mode by adding `EMBRACE_DEBUG_DSYM=1` to your run script:
+
+```bash
+EMBRACE_DEBUG_DSYM=1 EMBRACE_ID=YOUR_APP_ID EMBRACE_TOKEN=YOUR_API_TOKEN "${SRCROOT}/path/to/your/run.sh"
+```
+
+In debug mode, the upload runs synchronously and all logs appear directly in the Xcode build output. This slows down the build, so only enable it while troubleshooting.
+
 For more troubleshooting tips, see our [FAQ section](/ios/faq#troubleshooting-dsym-upload).
 
 ## Next Steps

docs/ios/best-practices/ci-dsym-upload.md

@@ -135,15 +135,15 @@ It's also possible to manually run the Embrace upload tool directly from a CI st
 The `APP_KEY` and `API_TOKEN` envvars should be retrieved from the Embrace dashboard.
 
 ```shell-session
-/path/to/EmbraceIO/embrace_symbol_upload.darwin -app $APP_KEY -token $API_TOKEN dsym_output.zip
+/path/to/EmbraceIO/embrace_symbol_upload.darwin --app $APP_KEY --token $API_TOKEN dsym_output.zip
 ```
 
 If the Embrace `embrace_symbol_upload.darwin` utility is in a known location you should use the existing binary. If it is non-deterministic or not included alongside the Embrace package itself, then you can download the utility directly.
 
 ```shell-session
 curl -o ./embrace_support.zip https://downloads.embrace.io/embrace_support.zip
 unzip ./embrace_support.zip
-./embrace_symbol_upload.darwin -app $APP_KEY -token $API_TOKEN dsym_output.zip
+./embrace_symbol_upload.darwin --app $APP_KEY --token $API_TOKEN dsym_output.zip
 ```
 
 ## Working with Xcode Cloud
@@ -181,7 +181,7 @@ then
   unzip ./embrace_support.zip
 
   # call Embrace upload tool
-  ./embrace_symbol_upload.darwin -app $APP_ID -token $EMBRACE_TOKEN ~/dsym_output.zip
+  ./embrace_symbol_upload.darwin --app $APP_ID --token $EMBRACE_TOKEN ~/dsym_output.zip
 fi
 ```
 

docs/product/settings/app-settings/dsym-symbols.md

@@ -18,6 +18,8 @@ Available artifacts include:
 
 Upload iOS/macOS dSYMs and view upload history. Valid dSYMs enable symbolicated crash stacks.
 
+Embrace performs symbolication server-side and retroactively. When a dSYM is uploaded after crashes have already been received, Embrace automatically re-symbolicates those older crashes with the newly available symbols. This means crash grouping remains consistent regardless of when the dSYM was uploaded.
+
 Developers can use DSYMs to:
 
 - Ensure iOS crashes show symbolicated function names and files.

docs/react-native/5x/integration/upload-symbol-files.md

@@ -37,7 +37,7 @@ Change the contents to the following:
 ```shell-session
 export NODE_BINARY=node
 
-export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/main.jsbundle.map"; <-- Add this line
+export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/main.jsbundle.map"; # <-- Add this line
 
 ../node_modules/react-native/scripts/react-native-xcode.sh
 ```