diff --git a/CHANGELOG.md b/CHANGELOG.md index b348d28..3a5c1b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,8 @@ should stay on 9.x: there is no compatibility layer (the decision is open), see ### Requirements * Flutter 3.50.0 or newer, Dart 3.14 or newer (the 10.0 major moves the floor to the release with Direct Interop, Android Gradle Plugin 9 and `material_ui`; it was 3.41.0 / 3.11, the first where a SwiftPM-only plugin resolves on Linux and Windows). +* Android: turn on the native symbol upload with `bugsee { ndk { enabled.set(true) } }` (the plugin has it off; without it native crashes + in release builds are unreadable), see README "Debug symbols" (also the Dart and iOS symbols, which are uploaded by hand). * Android: `minSdk` 21, JDK 17 or 21, the Bugsee Gradle plugin 4.1.1 applied by the app (mandatory; no Gradle ordering workaround any more, [bugsee-android-gradle-plugin#33](https://github.com/bugsee/bugsee-android-gradle-plugin/issues/33) is fixed in 4.1.0). * iOS: 15.0 or newer, Swift Package Manager only (no CocoaPods). diff --git a/README.md b/README.md index 96ef50a..c1acea7 100644 --- a/README.md +++ b/README.md @@ -77,9 +77,28 @@ while the core is unpublished. fixed): the ordering snippet that 4.0.x needed on Gradle 8.14 (the old Flutter template) is gone (debug, release and profile builds of the example were measured without it). On an older plugin the build fails Gradle task validation on `injectBugseeBuildId`: use 4.1.1. -Nothing else is needed: the plugin declares `bugsee-android` **and** the separate `bugsee-android-ndk` artefact (native crash -detection), registers its wrapper from a content provider that runs before the SDK can launch, and ships consumer ProGuard -rules. The working example is [`example/android`](example/android). +3. **Turn on the native symbol upload** in `android/app/build.gradle.kts` (the Bugsee plugin has it OFF by default): + + ```kotlin + bugsee { + ndk { enabled.set(true) } + } + ``` + + The native crash detector itself is always present (this package depends on the separate `bugsee-android-ndk` artefact), but a + crash in `libflutter.so` or any other `.so` is only readable (function and file:line) when the backend has that build's + native symbols. With `ndk.enabled` the plugin uploads the unstripped libraries of every **non-debuggable** build (task + `uploadNative`, for example `uploadBugseeReleaseNative`) with the app token (`bugsee.properties` in the Gradle root directory, the + `android/` folder of a Flutter app, or `appToken("...")` in the `bugsee { }` block); without a token it skips quietly. The R8 mapping upload + needs no setting. See [Debug symbols](#debug-symbols) for the Dart and iOS symbols too. + +Besides that, the plugin registers this package's wrapper from a content provider that runs before the SDK can launch and the +package ships consumer ProGuard rules. The working example is [`example/android`](example/android). + +**Other Bugsee Android modules** (`bugsee-android-okhttp`, `-ktor-2`, `-ktor-3`, `-cronet`, `-compose`, `-leak`) are not added: they +instrument NATIVE UI and HTTP stacks (OkHttp, Ktor, Cronet, Jetpack Compose, native leak watching), which a Flutter UI and Dart's +`dart:io` network capture do not use. An app that has native code using one of them declares the dependency itself and the plugin +wires it. The feedback chat is the separate package `bugsee_flutter_feedback`. ### iOS @@ -333,6 +352,21 @@ Future contactSupport() async { } ``` +## Debug symbols + +A crash or error report is only readable when the backend holds the symbols of the build that produced it. Keep the symbols of +every build you ship. + +| What | Where it comes from | How it gets to Bugsee | +|---|---|---| +| Android Java/Kotlin frames (R8 mapping) | the Bugsee Gradle plugin | automatic, on every minified build (`uploadMapping`) | +| Android native frames (`libflutter.so`, your `.so` files) | the Bugsee Gradle plugin | **only with `bugsee { ndk { enabled.set(true) } }`** (see Install, Android); non-debuggable builds | +| Dart frames of a release build made with `--split-debug-info` (and `--obfuscate`) | `build/symbols/*.symbols` | **manual**: [doc/exceptions.md](doc/exceptions.md) section 5 (the 9.x `symbols.py` script; `bugsee-cli` has no Flutter type yet) | +| iOS native frames (the app, `Flutter.framework`) | the build's dSYMs | **manual in a Flutter app**: a Run Script phase after "Embed Frameworks" running `bugsee-cli xcode upload-dsyms --app-token "$BUGSEE_APP_TOKEN"` ([Bugsee CLI, Xcode](https://docs.bugsee.com/cli/xcode/)), or `bugsee-cli debug-files upload /dSYMs --type dsym --version --build ` in CI; with Xcode 15 and newer set `ENABLE_USER_SCRIPT_SANDBOXING = NO` on the target; `$BUGSEE_APP_TOKEN` must exist in the script's environment (a user-defined build setting of the target named `BUGSEE_APP_TOKEN` does that), and the CLI fails the build, exit code 20, when it is missing or empty | + +Dart symbols and iOS dSYMs are not uploaded for you by this package: nothing in a Flutter build calls the Bugsee uploader. The iOS +row is taken from Bugsee's CLI documentation and has not been measured with a Flutter build here. + ## Privacy model Bugsee records what makes a bug reproducible, so decide what must not be recorded. What is captured, and the control for each: diff --git a/example/android/.gitignore b/example/android/.gitignore index be3943c..aecfe5c 100644 --- a/example/android/.gitignore +++ b/example/android/.gitignore @@ -4,6 +4,7 @@ gradle-wrapper.jar /gradlew /gradlew.bat /local.properties +/bugsee.properties GeneratedPluginRegistrant.java .cxx/ diff --git a/example/android/app/build.gradle.kts b/example/android/app/build.gradle.kts index 071cecd..40845e1 100644 --- a/example/android/app/build.gradle.kts +++ b/example/android/app/build.gradle.kts @@ -38,3 +38,14 @@ android { flutter { source = "../.." } + +// Native crash FRAMES are only readable with the native symbols: this uploads the unstripped +// libraries (libflutter.so and the other .so files the app packages) of each non-debuggable build, +// keyed by build id; a library that ships already stripped stays unsymbolicated. It is OFF by default +// in the plugin; without it a native crash in a release build reaches the backend as raw addresses. +// It needs the app token: `bugsee.properties` in the Gradle ROOT directory (`example/android`, the +// plugin reads `/bugsee.properties`; do not commit a real token) or `appToken("...")` +// here; with none it skips quietly. +bugsee { + ndk { enabled.set(true) } +} diff --git a/test/native_versions_test.dart b/test/native_versions_test.dart index 0c53d0d..c352d16 100644 --- a/test/native_versions_test.dart +++ b/test/native_versions_test.dart @@ -139,6 +139,26 @@ void main() { contains('id("com.bugsee.android.gradle")'), ); }); + + test('example turns the native symbol upload on (off by default in the plugin)', () { + // Without it a native crash in a release build reaches the backend as raw addresses. + // A live statement, not text in a comment or in a disabled block: the line starts with the code. + expect( + read('example/android/app/build.gradle.kts'), + matches( + RegExp( + r'^bugsee\s*\{\s*ndk\s*\{\s*enabled\.set\(true\)\s*\}\s*\}', + multiLine: true, + ), + ), + ); + // The token file the comment and the README name is the one the plugin reads and git ignores. + expect( + read('example/android/.gitignore'), + contains('/bugsee.properties'), + ); + expect(read('README.md'), contains('ndk { enabled.set(true) }')); + }); }); group('iOS', () {