|
| 1 | +# Bugsee |
| 2 | + |
| 3 | +This project include [Bugsee](https://www.bugsee.com/) reporting and Logging, for both Android and iOS apps. |
| 4 | +Bugsee lets you monitor and get instant log of unhandled exceptions with traces, events, stacktrace and videos/screenshots of the reported exception. More features are provided by Bugsee like data obscuration and log filter. |
| 5 | + |
| 6 | +For this implementation we've used [bugsee_flutter](https://pub.dev/packages/bugsee_flutter) package. |
| 7 | + |
| 8 | +- By default only release apps will have Bugsee reporting enabled, to enable Bugsee in debug mode add your token in `launch.json` add remove the check on debug mode in `BugseeManager` class. |
| 9 | +- **Token** |
| 10 | + - Generate your token in order to test Bugsee logging and reporting |
| 11 | + - Head to [Bugsee dashboard](https://www.bugsee.com/) |
| 12 | + - Create a new account |
| 13 | + - Create a new Android/iOS (choose Flutter framework) |
| 14 | + - Copy-paste the generated token into `launch.json` |
| 15 | + |
| 16 | + |
| 17 | +## 1) Features |
| 18 | + |
| 19 | +In this project we've implemented the following features of Bugsee: |
| 20 | +- [Manual invocation](https://docs.bugsee.com/sdk/flutter/manual/) helpfull for developers to test their Bugsee integration and setup with new tokens. |
| 21 | +- [Custom data](https://docs.bugsee.com/sdk/flutter/custom/) custom data could be attached to the logged exceptions (emails or other type of data) |
| 22 | + - [Email](https://docs.bugsee.com/sdk/flutter/custom/#:~:text=Adding%20custom%20data-,User%20email,-When%20you%20already) this will identify the user whom experienced the exception/bug this will update the exception dashboard item from anonymous to the user's mail this data will be reported with every logged exception unless the app is deleted or removed manually. |
| 23 | + - [Attributes](https://docs.bugsee.com/sdk/flutter/custom/#:~:text=User/Session%20attributes) attributes related to the user info, will be reported with every logged exception unless the app is deleted or removed manually. |
| 24 | + - [Traces](https://docs.bugsee.com/sdk/flutter/custom/#:~:text=them%0ABugsee.clearAllAttributes()%3B-,Custom%20traces,-Traces%20may%20be) helpfull when developer want to track the change of specific value before the logging of the exception. |
| 25 | + - [Events](https://docs.bugsee.com/sdk/flutter/custom/#:~:text=Custom%20events-,Events,-are%20identified%20by) highlight on which event the exception is logged, accept also json data attached to it. |
| 26 | +- [Exception Logging](https://docs.bugsee.com/sdk/flutter/logs/) the app automatically log every unhandled exception: Dart SDK exception are related to data or logic errors and Flutter SDK errors that are related to layout and rendering issues. The implementation also offer an API to manually log an exception with traces and events. |
| 27 | +- [Video Capturing](https://docs.bugsee.com/sdk/flutter/privacy/video/) video capturing is by default enabled in this project, but it can be turned off using the `videoEnabled` flag in the launchOptions object for Android and iOS. |
| 28 | +- [Log reporting](https://docs.bugsee.com/sdk/flutter/privacy/logs/) all logs are filtered by default using the `_filterBugseeLogs` method, this can be turned off from the app or by removing the call to `setLogFilter` Bugsee method. |
| 29 | +- [Obscure Data](https://docs.bugsee.com/sdk/flutter/privacy/video/#:~:text=Protecting%20flutter%20views): data obscuration is by default enabled in the project in order to protect user-related data from being leaked through captured videos. |
| 30 | + |
| 31 | +**Default configurations:** |
| 32 | +Data obscuration, log collection, log filter and attaching log file features are initialized from the `.env.staging` file. |
| 33 | +``` |
| 34 | +BUGSEE_IS_DATA_OBSCURE=true |
| 35 | +BUGSEE_DISABLE_LOG_COLLECTION=true |
| 36 | +BUGSEE_FILTER_LOG_COLLECTION=false |
| 37 | +BUGSEE_ATTACH_LOG_FILE=true |
| 38 | +``` |
| 39 | + |
| 40 | +## 2) Implementation |
| 41 | +- [Bugsee Manager](../src/app/lib/business/bugsee/bugsee_manager.dart): a service class that handle the Bugsee intialization, capturing logs, customize Bugsee fields and features (Video capture, data obscure, logs filter...) . |
| 42 | +- [Bugsee Config State](../src/app/lib/business/bugsee/bugsee_config_state.dart): a state class holds all the actual Bugsee features status (whether enabled or not). |
| 43 | +- [Bugsee Repository](../src/app/lib/access/bugsee/bugsee_repository.dart): save and retrieve Bugsee configuration from the shared preference storage. |
| 44 | +- [Bugsee saved configuration](../src/app/lib/access/bugsee/bugsee_configuration_data.dart): holds the Bugsee saved configuration in shared preference, used in [Bugsee Manager](../src/app/lib/business/bugsee/bugsee_manager.dart) to initialize [Bugsee Config State](../src/app/lib/business/bugsee/bugsee_config_state.dart). |
| 45 | + |
| 46 | +### Intecepting exceptions |
| 47 | +Bugsee implementation in this project, by default intecepts all the unhandled Dart and Flutter exception. |
| 48 | + |
| 49 | +`main.dart` |
| 50 | +```dart |
| 51 | +runZonedGuarded( |
| 52 | + () async { |
| 53 | + FlutterError.onError = |
| 54 | + GetIt.I.get<BugseeManager>().inteceptRenderExceptions; |
| 55 | + await initializeComponents(); |
| 56 | + await registerBugseeManager(); |
| 57 | + runApp(const App()); |
| 58 | + }, |
| 59 | + GetIt.I.get<BugseeManager>().inteceptExceptions, |
| 60 | + ); |
| 61 | +``` |
| 62 | +the `inteceptExceptions` and `inteceptRenderExceptions` recerespectively report Dart and Flutter exceptions to the Bugsee Dashboard. |
| 63 | + |
| 64 | +`inteceptExceptions` |
| 65 | +```dart |
| 66 | +@override |
| 67 | + Future<void> inteceptExceptions( |
| 68 | + Object error, |
| 69 | + StackTrace stackTrace, |
| 70 | + ) async { |
| 71 | + String? message = switch (error.runtimeType) { |
| 72 | + const (PersistenceException) => (error as PersistenceException).message, |
| 73 | + _ => null, |
| 74 | + }; |
| 75 | + await logException( |
| 76 | + exception: Exception(error), |
| 77 | + stackTrace: stackTrace, |
| 78 | + traces: { |
| 79 | + 'message': message, |
| 80 | + }, |
| 81 | + ); |
| 82 | + } |
| 83 | +``` |
| 84 | + |
| 85 | +`inteceptRenderExceptions` |
| 86 | +```dart |
| 87 | +@override |
| 88 | + Future<void> inteceptRenderExceptions(FlutterErrorDetails error) async { |
| 89 | + await logException( |
| 90 | + exception: Exception(error.exception), |
| 91 | + stackTrace: error.stack, |
| 92 | + ); |
| 93 | + } |
| 94 | +``` |
| 95 | + |
| 96 | +### Manually invoke report dialog |
| 97 | + |
| 98 | +To manually display the report dialog, you call the `showCaptureLogReport` method from the `BugseeManager` class. |
| 99 | + |
| 100 | +```dart |
| 101 | +final bugseeManager = Get.I.get<BugseeManager>(); |
| 102 | +bugseeManger.showCaptureLogReport(); |
| 103 | +``` |
| 104 | + |
| 105 | + |
| 106 | +### Manually log an exception |
| 107 | + |
| 108 | +To manually log an exception, you call the `logException` method from the `BugseeManager` class. You can add traces and events to the reported exception. |
| 109 | + |
| 110 | +```dart |
| 111 | +final bugseeManager = Get.I.get<BugseeManager>(); |
| 112 | +bugseeManger.logException(exception: Exception()); |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +### Add attributes |
| 117 | + |
| 118 | +To attach the user's email to the logged exception use `addEmailAttribute` method and to clear this attribute you can use `clearEmailAttribute`. |
| 119 | + |
| 120 | +```dart |
| 121 | +final bugseeManager = Get.I.get<BugseeManager>(); |
| 122 | +bugseeManger.addEmailAttribute("johndoe@nventive.com"); |
| 123 | +//some other code.. |
| 124 | +bugseeManger.clearEmailAttribute(); |
| 125 | +``` |
| 126 | + |
| 127 | +for other attributes you can use `addAttributes` with a map where key is the attribute name and value is the attribute value. To clear these attributes use `clearAttribute` and pass the attribute name to it. |
| 128 | + |
| 129 | +```dart |
| 130 | +final bugseeManager = Get.I.get<BugseeManager>(); |
| 131 | +bugseeManger.addAttributes({ |
| 132 | + 'name': 'john', |
| 133 | + 'age': 45, |
| 134 | +}); |
| 135 | +//some other code.. |
| 136 | +bugseeManger.clearAttribute('name'); |
| 137 | +``` |
| 138 | + |
| 139 | +## 3) Deployment |
| 140 | + |
| 141 | +The Bugsee token is injected directly in the azure devops pipeline when building the Android/iOS app for release mode in the [Android Build Job](../build/steps-build-android.yml) and [iOS Build Job](../build/steps-build-ios.yml) under the `multiDartDefine` parameter. |
0 commit comments