feat: autocapture unhandled exceptions

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## Next
 
 - feat: add manual error capture ([#212](https://github.com/PostHog/posthog-flutter/pull/212))
+- feat: add autocapture of Flutter and Dart exceptions ([#214](https://github.com/PostHog/posthog-flutter/pull/214))
 
 ## 5.6.0
 

android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt

@@ -535,13 +535,17 @@ class PosthogFlutterPlugin :
         }
     }
 
-    private fun captureException(call: MethodCall, result: Result) {
+    private fun captureException(
+        call: MethodCall,
+        result: Result,
+    ) {
         try {
-            val arguments = call.arguments as? Map<String, Any> ?: run {
-                result.error("INVALID_ARGUMENTS", "Invalid arguments for captureException", null)
-                return
-            }
-
+            val arguments =
+                call.arguments as? Map<String, Any> ?: run {
+                    result.error("INVALID_ARGUMENTS", "Invalid arguments for captureException", null)
+                    return
+                }
+
             PostHog.capture("\$exception", properties = arguments)
             result.success(null)
         } catch (e: Exception) {

example/lib/main.dart

@@ -17,6 +17,23 @@ Future<void> main() async {
   config.sessionReplayConfig.maskAllImages = false;
   config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);
   config.flushAt = 1;
+
+  // Configure error tracking and exception capture
+  config.errorTrackingConfig.captureUnhandledExceptions =
+      true; // Enable autocapture
+  config.errorTrackingConfig.captureFlutterErrors =
+      true; // Capture Flutter framework errors
+  config.errorTrackingConfig.captureDartErrors =
+      true; // Capture Dart runtime errors
+  // Configure exception filtering
+  config.errorTrackingConfig.shouldCaptureException = (error) {
+    // Example: Don't capture StateError exceptions
+    if (error is StateError) return false;
+
+    // Capture all other exceptions
+    return true;
+  };
+
   await Posthog().setup(config);
 
   runApp(const MyApp());
@@ -321,6 +338,59 @@ class InitialScreenState extends State<InitialScreen> {
                   child: const Text("Capture Exception (Background)"),
                 ),
                 const Divider(),
+                const Padding(
+                  padding: EdgeInsets.all(8.0),
+                  child: Text(
+                    "Exception Autocapture",
+                    style: TextStyle(fontWeight: FontWeight.bold),
+                  ),
+                ),
+                Wrap(
+                  alignment: WrapAlignment.spaceEvenly,
+                  spacing: 8.0,
+                  runSpacing: 8.0,
+                  children: [
+                    ElevatedButton(
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor:
+                            const Color.fromARGB(255, 207, 145, 218),
+                        foregroundColor: Colors.black,
+                      ),
+                      onPressed: () {
+                        // This will be automatically captured by FlutterError.onError
+                        throw FlutterError(
+                            'This is an unhandled Flutter error for autocapture demo');
+                      },
+                      child: const Text("Throw Flutter Error"),
+                    ),
+                    ElevatedButton(
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor: Colors.tealAccent,
+                        foregroundColor: Colors.black,
+                      ),
+                      onPressed: () {
+                        // This will be automatically captured by PlatformDispatcher.onError
+                        Future.microtask(() {
+                          throw MyCustomException(
+                              'This is an unhandled Dart error for autocapture demo');
+                        });
+                      },
+                      child: const Text("Throw Dart Error"),
+                    ),
+                    ElevatedButton(
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor: const Color.fromARGB(255, 44, 106, 53),
+                        foregroundColor: Colors.white,
+                      ),
+                      onPressed: () {
+                        throw StateError(
+                            'This should not appear in PostHog if ignored in configuration');
+                      },
+                      child: const Text("Throw Flutter Error (Ignored)"),
+                    ),
+                  ],
+                ),
+                const Divider(),
                 const Padding(
                   padding: EdgeInsets.all(8.0),
                   child: Text(
@@ -520,7 +590,19 @@ class ThirdRoute extends StatelessWidget {
   }
 }
 
-/// Custom exception class for demonstration purposes
+/// Custom exception classes for demonstration purposes
+
+class MyCustomException implements Exception {
+  final String message;
+
+  MyCustomException(this.message);
+
+  @override
+  String toString() {
+    return 'MyCustomException: $message';
+  }
+}
+
 class CustomException implements Exception {
   final String message;
   final String? code;

ios/Classes/PosthogFlutterPlugin.swift

@@ -684,7 +684,7 @@ extension PosthogFlutterPlugin {
             result(FlutterError(code: "INVALID_ARGUMENTS", message: "Invalid arguments for captureException", details: nil))
             return
         }
-        
+
         PostHogSDK.shared.capture("$exception", properties: arguments)
         result(nil)
     }

lib/src/exceptions/posthog_error_tracking_autocapture_integration.dart

@@ -0,0 +1,175 @@
+import 'dart:ui';
+import 'package:flutter/foundation.dart';
+
+import '../posthog_config.dart';
+import '../posthog_flutter_platform_interface.dart';
+
+/// Handles automatic capture of Flutter and Dart exceptions
+class PostHogErrorTrackingAutoCaptureIntegration {
+  final PostHogErrorTrackingConfig _config;
+  final PosthogFlutterPlatformInterface _posthog;
+
+  // Store original handlers (we'll chain with them from our handler)
+  FlutterExceptionHandler? _originalFlutterErrorHandler;
+  ErrorCallback? _originalPlatformErrorHandler;
+
+  bool _isEnabled = false;
+
+  static PostHogErrorTrackingAutoCaptureIntegration? _instance;
+
+  PostHogErrorTrackingAutoCaptureIntegration._({
+    required PostHogErrorTrackingConfig config,
+    required PosthogFlutterPlatformInterface posthog,
+  })  : _config = config,
+        _posthog = posthog;
+
+  /// Install the autocapture integration (can only be installed once)
+  static PostHogErrorTrackingAutoCaptureIntegration? install({
+    required PostHogErrorTrackingConfig config,
+    required PosthogFlutterPlatformInterface posthog,
+  }) {
+    if (_instance != null) {
+      debugPrint(
+          'PostHog: Error tracking autocapture integration is already installed. Call PostHogErrorTrackingAutoCaptureIntegration.uninstall() first.');
+      return null;
+    }
+
+    _instance = PostHogErrorTrackingAutoCaptureIntegration._(
+      config: config,
+      posthog: posthog,
+    );
+
+    if (config.captureUnhandledExceptions) {
+      _instance!.start();
+    }
+
+    return _instance;
+  }
+
+  /// Uninstall the autocapture integration
+  static void uninstall() {
+    if (_instance != null) {
+      _instance!.stop();
+      _instance = null;
+    }
+  }
+
+  /// Start automatic exception capture
+  void start() {
+    if (_isEnabled) return;
+
+    _isEnabled = true;
+
+    // Set up Flutter error handler if enabled
+    if (_config.captureFlutterErrors) {
+      _setupFlutterErrorHandler();
+    }
+
+    // Set up platform error handler if enabled
+    if (_config.captureDartErrors) {
+      _setupPlatformErrorHandler();
+    }
+  }
+
+  /// Stop automatic exception capture (restores original handlers)
+  void stop() {
+    if (!_isEnabled) return;
+
+    _isEnabled = false;
+
+    // Restore original handlers
+    if (_originalFlutterErrorHandler != null) {
+      FlutterError.onError = _originalFlutterErrorHandler;
+      _originalFlutterErrorHandler = null;
+    }
+
+    if (_originalPlatformErrorHandler != null) {
+      PlatformDispatcher.instance.onError = _originalPlatformErrorHandler;
+      _originalPlatformErrorHandler = null;
+    }
+  }
+
+  /// Flutter framework error handler
+  void _setupFlutterErrorHandler() {
+    // prevent circular calls
+    if (FlutterError.onError == _posthogFlutterErrorHandler) {
+      return;
+    }
+
+    _originalFlutterErrorHandler = FlutterError.onError;
+
+    FlutterError.onError = _posthogFlutterErrorHandler;
+  }
+
+  void _posthogFlutterErrorHandler(FlutterErrorDetails details) {
+    // don't capture silent errors (could maybe be a config?)
+    if (!details.silent) {
+      _captureException(
+        error: details.exception,
+        stackTrace: details.stack,
+        handled: false,
+        context: details.context?.toString(),
+      );
+    }
+
+    // Call the original handler
+    if (_originalFlutterErrorHandler != null) {
+      try {
+        _originalFlutterErrorHandler!(details);
+      } catch (e) {
+        // Pretty sure we should be doing this to avoid infinite loops
+        debugPrint(
+            'PostHog: Error in original FlutterError.onError handler: $e');
+      }
+    } else {
+      // If no original handler, use the default behavior (default is to dump to console)
+      FlutterError.presentError(details);
+    }
+  }
+
+  /// Platform error handler for Dart runtime errors
+  void _setupPlatformErrorHandler() {
+    // prevent circular calls
+    if (PlatformDispatcher.instance.onError == _posthogPlatformErrorHandler) {
+      return;
+    }
+
+    _originalPlatformErrorHandler = PlatformDispatcher.instance.onError;
+    PlatformDispatcher.instance.onError = _posthogPlatformErrorHandler;
+  }
+
+  bool _posthogPlatformErrorHandler(Object error, StackTrace stackTrace) {
+    _captureException(
+        error: error,
+        stackTrace: stackTrace,
+        handled: false,
+        context: 'Platform error');
+
+    // Call the original handler
+    if (_originalPlatformErrorHandler != null) {
+      try {
+        return _originalPlatformErrorHandler!(error, stackTrace);
+      } catch (e) {
+        debugPrint(
+            'PostHog: Error in original PlatformDispatcher.onError handler: $e');
+        return true; // Consider the error handled
+      }
+    }
+
+    return false; // No original handler, don't modify behavior
+  }
+
+  Future<void> _captureException({
+    required dynamic error,
+    required StackTrace? stackTrace,
+    required bool handled,
+    String? context,
+  }) {
+    return _posthog.captureException(
+      error: error,
+      stackTrace: stackTrace ?? StackTrace.current,
+      properties: context != null ? {'context': context} : null,
+      handled: handled,
+    );
+  }
+}

lib/src/posthog.dart

@@ -1,5 +1,6 @@
 import 'package:meta/meta.dart';
 
+import 'exceptions/posthog_error_tracking_autocapture_integration.dart';
 import 'posthog_config.dart';
 import 'posthog_flutter_platform_interface.dart';
 import 'posthog_observer.dart';
@@ -24,9 +25,27 @@ class Posthog {
   /// com.posthog.posthog.AUTO_INIT: false
   Future<void> setup(PostHogConfig config) {
     _config = config; // Store the config
+
+    installFlutterIntegrations(config);
+
     return _posthog.setup(config);
   }
 
+  void installFlutterIntegrations(PostHogConfig config) {
+    // Install exception autocapture if enabled
+    if (config.errorTrackingConfig.captureUnhandledExceptions) {
+      PostHogErrorTrackingAutoCaptureIntegration.install(
+        config: config.errorTrackingConfig,
+        posthog: _posthog,
+      );
+    }
+  }
+
+  void uninstallFlutterIntegrations() {
+    // Uninstall exception autocapture integration
+    PostHogErrorTrackingAutoCaptureIntegration.uninstall();
+  }
+
   @internal
   PostHogConfig? get config => _config;
 
@@ -85,7 +104,12 @@ class Posthog {
 
   Future<void> reset() => _posthog.reset();
 
-  Future<void> disable() => _posthog.disable();
+  Future<void> disable() {
+    // Uninstall Flutter-specific integrations when disabling
+    uninstallFlutterIntegrations();
+
+    return _posthog.disable();
+  }
 
   Future<void> enable() => _posthog.enable();
 
@@ -147,6 +171,10 @@ class Posthog {
     _config = null;
     _currentScreen = null;
     PosthogObserver.clearCurrentContext();
+
+    // Uninstall Flutter integrations
+    uninstallFlutterIntegrations();
+
     return _posthog.close();
   }