feat: add manual error capture

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Next
 
+- feat: add manual error capture ([#212](https://github.com/PostHog/posthog-flutter/pull/212))
+- **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,35 @@ 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
+                }
+
+            var properties = arguments.toMutableMap() // make mutable
+
+            // Extract timestamp from Flutter
+            var timestamp: Date? = null
+            val timestampMs = properties["timestamp"] as? Long
+            if (timestampMs != null) {
+                // timestampMs already in UTC milliseconds epoch
+                timestamp = Date(timestampMs)
+                properties.remove("timestamp")
+            }
+
+            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

@@ -1,3 +1,4 @@
+import 'dart:isolate';
 import 'package:flutter/material.dart';
 import 'package:posthog_flutter/posthog_flutter.dart';
 
@@ -21,6 +22,28 @@ Future<void> main() async {
   runApp(const MyApp());
 }
 
+/// This function runs in a separate isolate with its own sandboxed thread, meant to demonstate capturing exceptions from background "threads"
+void _backgroundIsolateEntryPoint(SendPort sendPort) async {
+  await Future.delayed(const Duration(milliseconds: 500));
+
+  try {
+    // Simulate an exception in the background isolate
+    throw StateError('Background isolate processing failed!');
+  } catch (e, stack) {
+    // Send exception data back to main isolate for capture
+    sendPort.send({
+      'error': e.toString(),
+      'errorType': e.runtimeType.toString(),
+      'stackTrace': stack.toString(),
+      'properties': {
+        'test_type': 'background_isolate_exception',
+        'isolate_name': 'exception-demo-worker',
+        'button_pressed': 'capture_exception_background',
+      },
+    });
+  }
+}
+
 class MyApp extends StatefulWidget {
   const MyApp({super.key});
 
@@ -240,6 +263,77 @@ 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 (Main)"),
+                ),
+                ElevatedButton(
+                  style: ElevatedButton.styleFrom(
+                    backgroundColor: Colors.orange,
+                  ),
+                  onPressed: () async {
+                    // Capture exception from background isolate
+                    await _captureExceptionFromBackgroundIsolate();
+                  },
+                  child: const Text("Capture Exception (Background)"),
+                ),
+                ElevatedButton(
+                  style: ElevatedButton.styleFrom(
+                    backgroundColor: Colors.orange,
+                  ),
+                  onPressed: () async {
+                    // Capture exception from background isolate
+                    await Posthog().captureException(
+                      error: 'No Stack Trace Error',
+                      properties: {'test_type': 'no_stack_trace'},
+                    );
+                  },
+                  child: const Text("Capture Exception (No Stack)"),
+                ),
+                const Divider(),
                 const Padding(
                   padding: EdgeInsets.all(8.0),
                   child: Text(
@@ -300,6 +394,53 @@ class InitialScreenState extends State<InitialScreen> {
       ),
     );
   }
+
+  /// Demonstrates exception capture from a background isolate
+  /// This should show a different thread_id than the main isolate
+  Future<void> _captureExceptionFromBackgroundIsolate() async {
+    final receivePort = ReceivePort();
+
+    // Spawn a background isolate with a custom name for demonstration
+    await Isolate.spawn(
+      _backgroundIsolateEntryPoint,
+      receivePort.sendPort,
+      debugName: 'custom-isolate-name-will-be-hashed-as-thread_id',
+    );
+
+    // Wait for the isolate to complete (or timeout after 5 seconds)
+    final result = await receivePort.first.timeout(
+      const Duration(seconds: 5),
+      onTimeout: () => {'type': 'timeout'},
+    );
+
+    if (result is Map<String, dynamic>) {
+      // Reconstruct the stack trace from the string
+      final stackTrace = StackTrace.fromString(result['stackTrace']);
+
+      // Create a synthetic error with the original error message and type
+      final syntheticError =
+          Exception('${result['errorType']}: ${result['error']}');
+
+      await Posthog().captureException(
+        error: syntheticError,
+        stackTrace: stackTrace,
+        properties: Map<String, Object>.from(result['properties'] ?? {}),
+      );
+
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          const SnackBar(
+            content: Text(
+                'Background isolate exception captured successfully! Check PostHog.'),
+            backgroundColor: Colors.green,
+            duration: Duration(seconds: 3),
+          ),
+        );
+      }
+    }
+
+    receivePort.close();
+  }
 }
 
 class SecondRoute extends StatefulWidget {
@@ -391,3 +532,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';
+  }
+}

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,26 @@ 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
+        }
+
+        var properties = arguments // make mutable
+
+        // Extract timestamp from Flutter and convert to Date
+        var timestamp: Date? = nil
+        if let timestampMs = properties["timestamp"] as? Int64 {
+            timestamp = Date(timeIntervalSince1970: TimeInterval(timestampMs) / 1000.0)
+            properties.removeValue(forKey: "timestamp")
+        }
+
+        // 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)