Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
40 changes: 37 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `injectBugsee<Variant>BuildId`: 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
`upload<Variant>Native`, 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

Expand Down Expand Up @@ -333,6 +352,21 @@ Future<void> 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 (`upload<Variant>Mapping`) |
| 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 <archive>/dSYMs --type dsym --version <v> --build <n>` 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:
Expand Down
1 change: 1 addition & 0 deletions example/android/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ gradle-wrapper.jar
/gradlew
/gradlew.bat
/local.properties
/bugsee.properties
GeneratedPluginRegistrant.java
.cxx/

Expand Down
11 changes: 11 additions & 0 deletions example/android/app/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<rootProject>/bugsee.properties`; do not commit a real token) or `appToken("...")`
// here; with none it skips quietly.
bugsee {
ndk { enabled.set(true) }
}
20 changes: 20 additions & 0 deletions test/native_versions_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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', () {
Expand Down
Loading