Flutter error tracking installation

  1. Install the package

    Required

    Add the PostHog Flutter SDK to your pubspec.yaml:

    pubspec.yaml
    posthog_flutter: ^5.0.0

  2. Platform setup

    Required

    Add these values to your AndroidManifest.xml:

    android/app/src/main/AndroidManifest.xml
    <application>
      <activity>
        [...]
      </activity>
      <meta-data android:name="com.posthog.posthog.API_KEY" android:value="<ph_project_api_key>" />
      <meta-data android:name="com.posthog.posthog.POSTHOG_HOST" android:value="https://us.i.posthog.com" />
      <meta-data android:name="com.posthog.posthog.TRACK_APPLICATION_LIFECYCLE_EVENTS" android:value="true" />
      <meta-data android:name="com.posthog.posthog.DEBUG" android:value="true" />
    </application>

    Update the minimum Android SDK version to 21 in android/app/build.gradle:

    android/app/build.gradle
    defaultConfig {
      minSdkVersion 21
      // rest of your config
    }

  3. Send events

    Recommended

    Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

    Dart
    import 'package:posthog_flutter/posthog_flutter.dart';
    

    await Posthog().capture(
        eventName: 'button_clicked',
        properties: {
          'button_name': 'signup'
        }
    );

  4. Set up exception autocapture

    Recommended
    Client-side configuration only

    This configuration is client-side only. Support for remote configuration in the error tracking settings will be added in a future release.

    You can autocapture exceptions by configuring the errorTrackingConfig when setting up PostHog:

    Dart
    final config = PostHogConfig('<ph_project_api_key>');
    // Enable exception autocapture
    config.errorTrackingConfig.captureFlutterErrors = true;
    config.errorTrackingConfig.capturePlatformDispatcherErrors = true;
    config.errorTrackingConfig.captureIsolateErrors = true;
    config.errorTrackingConfig.captureNativeExceptions = true;
    config.errorTrackingConfig.captureSilentFlutterErrors = false;
    await Posthog().setup(config);

    Configuration options:

    OptionDescription
    captureFlutterErrorsCaptures Flutter framework errors (FlutterError.onError)
    capturePlatformDispatcherErrorsCaptures Dart runtime errors (PlatformDispatcher.onError). Web not supported.
    captureIsolateErrorsCaptures errors from main isolate. Web not supported.
    captureNativeExceptionsCaptures native exceptions (Java/Kotlin exceptions). Android only.
    captureSilentFlutterErrorsCaptures Flutter errors that are marked as silent. Default: false.

  5. Manually capture exceptions

    Optional

    Basic usage

    You can manually capture exceptions using the captureException method:

    Dart
    try {
      // Your awesome code that may throw
      await someRiskyOperation();
    } catch (exception, stackTrace) {
      // Capture the exception with PostHog
      await Posthog().captureException(
        error: exception,
        stackTrace: stackTrace,
        properties: {
          'user_action': 'button_press',
          'feature_name': 'data_sync',
        },
      );
    }

    This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.

    Error tracking configuration

    You can configure error tracking behavior when setting up PostHog:

    Flutter web apps use minified stack trace frames

    Flutter web apps generate minified stack trace frames by default, which may cause the configurations below to behave differently or not work as expected.

    Dart
    final config = PostHogConfig('<ph_project_api_key>');
    // Configure error tracking
    config.errorTrackingConfig.inAppIncludes = ['package:your_app'];
    config.errorTrackingConfig.inAppExcludes = ['package:third_party_lib'];
    config.errorTrackingConfig.inAppByDefault = true;
    await Posthog().setup(config);

    Configuration options:

    OptionDescription
    inAppIncludesList of package names to be considered inApp frames (takes precedence over excludes)
    inAppExcludesList of package names to be excluded from inApp frames
    inAppByDefaultWhether frames are considered inApp by default when their origin cannot be determined

    inApp frames are stack trace frames that belong to your application code (as opposed to third-party libraries or system code). These are highlighted in the PostHog error tracking interface to help you focus on the relevant parts of the stack trace.

  6. Future features

    Optional

    We currently don't support the following features:

    • No de-obfuscating stacktraces from obfuscated builds (--obfuscate and --split-debug-info) for Dart code
    • No de-obfuscating stacktraces when isMinifyEnabled is enabled for Java/Kotlin code
    • No Source code context associated with an exception
    • No native iOS exception capture
    • No native C/C++ exception capture on Android (Java/Kotlin only)
    • No background isolate error capture

    These features will be added in future releases. We recommend you stay up to date with the latest version of the PostHog Flutter SDK.

  7. Verify error tracking

    Recommended
    Confirm events are being sent to PostHog
    Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
    Activity feed with events
    Check for exceptions in PostHog

  8. Upload source maps

    Required

    Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.

    Let's continue to the next section.

    Upload source maps

Community questions

Was this page useful?

Questions about this page? or post a community question.