feat: add manual error capture (#212)

* feat: add public interface

* feat: add config and exception processor

* feat: native plugins

* chore: update sample app

* feat: add unit tests

* feat: handle primitives

* chore: update changelog

* fix: package and module

* fix: format

* fix: use Object vs dynamic

* chore: rename folder

* fix: make stackTrace optional

* fix: clean generated stack trace

* feat: add unit tests

* fix: make function optional

* fix: drop primitive check

* fix: skip module

* fix: make thread_id optional

* fix: update config

* fix: error type

* fix: doc

* fix: handle empty stack trace

* fix: allow overwriting exception properties

* fix: normalize props

* chore: bump min dart and flutter version

* fix: generate event timestamp flutter side

* fix: remove handled from public api

* fix: platform call arguments

* fix: example app

* fix: do not try to parse exception package

* fix: normalize props

* fix: normalize sets

* fix: remove handled from public interface

* fix: web handler

* fix: replace hof with direct iteration

* fix:

* feat: add web support

* chore: add config comment

* feat: add async gap franes

* Revert "feat: add web support"

This reverts commit 6c0529c.

Author: ioannisj

CHANGELOG.md

@@ -1,5 +1,13 @@
 ## Next
 
+- feat: add manual error capture ([#212](https://github.com/PostHog/posthog-flutter/pull/212))
+  - **Note**: The following features are not yet supported:
+    - Automatic exception capture
+    - De-obfuscating stacktraces from obfuscated builds ([--obfuscate](https://docs.flutter.dev/deployment/obfuscate) and [--split-debug-info](https://docs.flutter.dev/deployment/obfuscate))
+    - [Source code context](/docs/error-tracking/stack-traces) associated with an exception
+    - Flutter web support
+  - **BREAKING**: Minimum Dart SDK version bumped to 3.4.0 and Flutter to 3.22.0 (required for `stack_trace` dependency compatibility)
+
 ## 5.6.0
 
 - feat: surveys use the new response question id format ([#210](https://github.com/PostHog/posthog-flutter/pull/210))

Makefile

@@ -1,4 +1,6 @@
-.PHONY: formatKotlin formatSwift formatDart checkDart installLinters
+.PHONY: format formatKotlin formatSwift formatDart checkDart installLinters test
+
+format: formatSwift formatKotlin formatDart
 
 installLinters:
 	brew install ktlint
@@ -19,3 +21,6 @@ checkFormatDart:
 
 analyzeDart:
 	dart analyze .
+
+test: 
+	flutter test -r expanded

android/build.gradle

@@ -54,8 +54,8 @@ android {
     dependencies {
         testImplementation 'org.jetbrains.kotlin:kotlin-test'
         testImplementation 'org.mockito:mockito-core:5.0.0'
-        // + Version 3.23.0 and the versions up to 4.0.0, not including 4.0.0 and higher
-        implementation 'com.posthog:posthog-android:[3.23.0,4.0.0]'
+        // + Version 3.25.0 and the versions up to 4.0.0, not including 4.0.0 and higher
+        implementation 'com.posthog:posthog-android:[3.25.0,4.0.0]'
     }
 
     testOptions {

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

@@ -19,6 +19,7 @@ import io.flutter.plugin.common.MethodCall
 import io.flutter.plugin.common.MethodChannel
 import io.flutter.plugin.common.MethodChannel.MethodCallHandler
 import io.flutter.plugin.common.MethodChannel.Result
+import java.util.Date
 
 /** PosthogFlutterPlugin */
 class PosthogFlutterPlugin :
@@ -156,6 +157,9 @@ class PosthogFlutterPlugin :
             "flush" -> {
                 flush(result)
             }
+            "captureException" -> {
+                captureException(call, result)
+            }
             "close" -> {
                 close(result)
             }
@@ -532,6 +536,34 @@ class PosthogFlutterPlugin :
         }
     }
 
+    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 properties = arguments["properties"] as? Map<String, Any>
+            val timestampMs = arguments["timestamp"] as? Long
+
+            // Extract timestamp from Flutter
+            val timestamp: Date? =
+                timestampMs?.let {
+                    // timestampMs already in UTC milliseconds epoch
+                    Date(timestampMs)
+                }
+
+            PostHog.capture("\$exception", properties = properties, timestamp = timestamp)
+            result.success(null)
+        } catch (e: Throwable) {
+            result.error("CAPTURE_EXCEPTION_ERROR", "Failed to capture exception: ${e.message}", null)
+        }
+    }
+
     private fun close(result: Result) {
         try {
             PostHog.close()

example/lib/main.dart

@@ -240,6 +240,66 @@ class InitialScreenState extends State<InitialScreen> {
                       child: Text("distinctId"),
                     )),
                 const Divider(),
+                const Padding(
+                  padding: EdgeInsets.all(8.0),
+                  child: Text(
+                    "Error Tracking",
+                    style: TextStyle(fontWeight: FontWeight.bold),
+                  ),
+                ),
+                ElevatedButton(
+                  onPressed: () async {
+                    try {
+                      // Simulate an exception in main isolate
+                      // throw 'a custom error string';
+                      // throw 333;
+                      throw CustomException(
+                        'This is a custom exception with additional context',
+                        code: 'DEMO_ERROR_001',
+                        additionalData: {
+                          'user_action': 'button_press',
+                          'timestamp': DateTime.now().millisecondsSinceEpoch,
+                          'feature_enabled': true,
+                        },
+                      );
+                    } catch (e, stack) {
+                      await Posthog().captureException(
+                        error: e,
+                        stackTrace: stack,
+                        properties: {
+                          'test_type': 'main_isolate_exception',
+                          'button_pressed': 'capture_exception_main',
+                          'exception_category': 'custom',
+                        },
+                      );
+
+                      if (mounted) {
+                        ScaffoldMessenger.of(context).showSnackBar(
+                          const SnackBar(
+                            content: Text(
+                                'Main isolate exception captured successfully! Check PostHog.'),
+                            backgroundColor: Colors.green,
+                            duration: Duration(seconds: 3),
+                          ),
+                        );
+                      }
+                    }
+                  },
+                  child: const Text("Capture Exception"),
+                ),
+                ElevatedButton(
+                  style: ElevatedButton.styleFrom(
+                    backgroundColor: Colors.orange,
+                  ),
+                  onPressed: () async {
+                    await Posthog().captureException(
+                      error: 'No Stack Trace Error',
+                      properties: {'test_type': 'no_stack_trace'},
+                    );
+                  },
+                  child: const Text("Capture Exception (Missing Stack)"),
+                ),
+                const Divider(),
                 const Padding(
                   padding: EdgeInsets.all(8.0),
                   child: Text(
@@ -391,3 +451,24 @@ class ThirdRoute extends StatelessWidget {
     );
   }
 }
+
+/// Custom exception class for demonstration purposes
+class CustomException implements Exception {
+  final String message;
+  final String? code;
+  final Map<String, dynamic>? additionalData;
+
+  const CustomException(
+    this.message, {
+    this.code,
+    this.additionalData,
+  });
+
+  @override
+  String toString() {
+    if (code != null) {
+      return 'CustomException($code): $message $additionalData';
+    }
+    return 'CustomException: $message $additionalData';
+  }
+}

example/pubspec.yaml

@@ -6,7 +6,7 @@ publish_to: "none" # Remove this line if you wish to publish to pub.dev
 version: 1.0.0+1
 
 environment:
-  sdk: '>=2.18.0 <4.0.0'
+  sdk: '>=3.4.0 <4.0.0'
   flutter: '>=3.3.0'
 
 # Dependencies specify other packages that your package needs in order to work.

ios/Classes/PosthogFlutterPlugin.swift

@@ -195,6 +195,8 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
             unregister(call, result: result)
         case "flush":
             flush(result)
+        case "captureException":
+            captureException(call, result: result)
         case "close":
             close(result)
         case "sendMetaEvent":
@@ -677,6 +679,25 @@ extension PosthogFlutterPlugin {
         result(nil)
     }
 
+    private func captureException(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
+        guard let arguments = call.arguments as? [String: Any] else {
+            result(FlutterError(code: "INVALID_ARGUMENTS", message: "Invalid arguments for captureException", details: nil))
+            return
+        }
+
+        let properties = arguments["properties"] as? [String: Any]
+
+        // Extract timestamp from Flutter and convert to Date
+        var timestamp: Date? = nil
+        if let timestampMs = arguments["timestamp"] as? Int64 {
+            timestamp = Date(timeIntervalSince1970: TimeInterval(timestampMs) / 1000.0)
+        }
+
+        // Use capture method with timestamp to ensure Flutter timestamp is used
+        PostHogSDK.shared.capture("$exception", properties: properties, timestamp: timestamp)
+        result(nil)
+    }
+
     private func close(_ result: @escaping FlutterResult) {
         PostHogSDK.shared.close()
         result(nil)