posthog_flutter

Patch Changes

• f3ccdee: Drop events when a before-send callback throws.

Patch Changes

• f3ccdee: Drop events when a before-send callback throws.

Patch Changes

• 3be4ded: Fix mobile session replay producing a blank recording after the session changes or the recording restarts — on idle or maximum-duration expiry, reset(), close()/setup(), or startSessionRecording(resumeCurrent: false). The new session now sends its own meta event and is sampled even on a screen that never repaints

Patch Changes

• 3be4ded: Fix mobile session replay producing a blank recording after the session changes or the recording restarts — on idle or maximum-duration expiry, reset(), close()/setup(), or startSessionRecording(resumeCurrent: false). The new session now sends its own meta event and is sampled even on a screen that never repaints

Patch Changes

• e07c8e7: Fix a session replay leak where masks could miss moving content. The mask rects are now computed in the same frame as the captured pixels, and a failed mask walk drops the frame instead of shipping an unmasked screenshot.

Patch Changes

• e07c8e7: Fix a session replay leak where masks could miss moving content. The mask rects are now computed in the same frame as the captured pixels, and a failed mask walk drops the frame instead of shipping an unmasked screenshot.

Patch Changes

• 26d457f: Draw survey close and check icons without requiring the Material Icons font.
• cbb7b59: Show surveys above nested navigator shell chrome and dismiss them through the root navigator.

Patch Changes

• 26d457f: Draw survey close and check icons without requiring the Material Icons font.
• cbb7b59: Show surveys above nested navigator shell chrome and dismiss them through the root navigator.

Patch Changes

• 57d9db3: Handle posthog-js errors raised while capturing exceptions on web.

Patch Changes

• 57d9db3: Handle posthog-js errors raised while capturing exceptions on web.

Patch Changes

• 910de24: Limit CocoaPods source compilation to Swift files when packaging the Darwin plugin.

Patch Changes

• 910de24: Limit CocoaPods source compilation to Swift files when packaging the Darwin plugin.

Minor Changes

• 15ee01b: Expose iOS and Mac Catalyst rage-click autocapture settings through PostHogConfig.rageClickConfig. Apps can disable $rageclick capture or configure its distance, timeout, and tap-count thresholds.

Minor Changes

• 15ee01b: Expose iOS and Mac Catalyst rage-click autocapture settings through PostHogConfig.rageClickConfig. Apps can disable $rageclick capture or configure its distance, timeout, and tap-count thresholds.

Patch Changes

• 220598f: Warn in debug builds when preloadFeatureFlags or bootstrap are set on Flutter web, where they are not applied, and document that identify/group reload feature flags

Patch Changes

• 220598f: Warn in debug builds when preloadFeatureFlags or bootstrap are set on Flutter web, where they are not applied, and document that identify/group reload feature flags

Minor Changes

• 2087837: Add push notification support so PostHog Workflows can target Flutter apps: device tokens register automatically on iOS and Android, notification opens are captured as $push_notification_opened, and registerPushNotificationToken, unregisterPushNotificationToken, and capturePushNotificationOpened cover the refresh and warm-start paths auto-detection cannot see.

  Both are enabled by default. An app that already has push configured (for example via firebase_messaging) starts sending its device token to PostHog after this upgrade with no code change. Set capturePushNotificationSubscriptions: false or capturePushNotificationOpened: false on PostHogConfig to opt out. Apps initialized via com.posthog.posthog.AUTO_INIT opt out with the com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_SUBSCRIPTIONS / com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_OPENED keys instead (Info.plist on iOS, AndroidManifest <meta-data> on Android), since the Dart-side config does not apply once the native SDK is already set up.

  pushIdentityProvider is a Dart callback, so it has no Info.plist or manifest equivalent: apps using com.posthog.posthog.AUTO_INIT must set it to false and call Posthog().setup(), otherwise the provider is never installed.

Minor Changes

• 2087837: Add push notification support so PostHog Workflows can target Flutter apps: device tokens register automatically on iOS and Android, notification opens are captured as $push_notification_opened, and registerPushNotificationToken, unregisterPushNotificationToken, and capturePushNotificationOpened cover the refresh and warm-start paths auto-detection cannot see.

  Both are enabled by default. An app that already has push configured (for example via firebase_messaging) starts sending its device token to PostHog after this upgrade with no code change. Set capturePushNotificationSubscriptions: false or capturePushNotificationOpened: false on PostHogConfig to opt out. Apps initialized via com.posthog.posthog.AUTO_INIT opt out with the com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_SUBSCRIPTIONS / com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_OPENED keys instead (Info.plist on iOS, AndroidManifest <meta-data> on Android), since the Dart-side config does not apply once the native SDK is already set up.

  pushIdentityProvider is a Dart callback, so it has no Info.plist or manifest equivalent: apps using com.posthog.posthog.AUTO_INIT must set it to false and call Posthog().setup(), otherwise the provider is never installed.

Patch Changes

• 1cb3a7c: Fix session replay masking on iOS and Android ignoring changed maskAllTexts/maskAllImages flags when setup() is called again

Patch Changes

• 3baf48d: Fix web canvas masking discarding an app-provided maskRegionsFn — canvases outside the Flutter view now get the app's original callback instead of recording unmasked

Minor Changes

• 0d8b279: Add session replay canvas masking on Flutter web: maskAllTexts, maskAllImages, PostHogMaskWidget, and obscured text fields now apply to the CanvasKit canvas — enable by declaring session_recording.canvasCapture.maskRegionsFn in posthog.init, or just by mounting a PostHogMaskWidget (requires posthog-js 1.408.0+)

Patch Changes

• 0d8b279: Fix maskAllTexts: false still masking Text widgets when maskAllImages is enabled

Patch Changes

• 69c8859: Clean up Android build warnings.

Patch Changes

• e835d19: Flutter web (WebAssembly): enabling captureIsolateErrors no longer crashes the app at startup. The isolate error handler was selected with a dart.library.html conditional import, which is false under dart2wasm, so wasm builds compiled the dart:isolate implementation and threw Unsupported operation: RawReceivePort before runApp — a white screen. The import now keys on dart.library.js_interop (true for both JS and wasm web builds), and the setup guard also skips isolate wiring on web explicitly. JS web builds and mobile/desktop are unaffected.

Patch Changes

• 771e558: Flutter web: PostHogWidget no longer runs the mobile session replay screenshot pipeline. On web, session replay is recorded by posthog-js, and every snapshot this pipeline produced was discarded — but it still walked the whole render tree twice per second (once for PostHogMaskWidget wrappers, once more when maskAllTexts or maskAllImages is on) for as long as the app was open. Web apps that enable sessionReplay and mount PostHogWidget no longer pay for that. Replay on web is unaffected, and PostHogWidget still mounts as before, so it remains safe to keep in a shared widget tree across web and mobile.

Patch Changes

• b9471d4: Session replay: masks every element that matched a masking rule, at any depth. The rect collector only walked two levels of the matched-element tree and dropped any node that had more than one matched child, so with maskAllTexts/maskAllImages enabled a PostHogMaskWidget wrapping several masked children lost its own mask rect, and whatever it wrapped that matched no rule on its own (a decorated container, a chart, a custom-painted avatar) stayed visible in the recording. More of the screen is masked as a result: a PostHogMaskWidget now covers its whole subtree, as documented, instead of only the children that matched.

Minor Changes

• 34dde19: Emit Dart error-tracking stack frames in PostHog's canonical bottom-up wire order: $exception_list[].stacktrace.frames[0] is now the outermost/entry-point frame and the last frame is the crash site (previously innermost-first). Applies to the primary exception and every cause in the chain. Raise the Android SDK floor to 3.56.0 so native Android exceptions use the same canonical order; Apple-native exceptions already do.

Patch Changes

• bbf20fa: Android: session replay screenshots are decoded, re-encoded, and queued off the main thread. Previously each frame cost the main thread 25-75ms on midrange hardware (up to once per second while recording), a visible per-second hitch during scrolling — iOS already did this work on a background queue.

Minor Changes

• 22dbde4: Session replay can now capture native screens that cover the Flutter app (full-screen paywalls, presented view controllers, native activities). Opt in with captureNativeScreens = true: while a native screen is up, capture is handed to the native PostHog SDK so it becomes visible in replay (requires native SDK support). When enabled but the capture cannot be produced, a black placeholder frame is shown for that screen instead. Off by default — with the flag off nothing is captured or blanked, and replay keeps showing the covered Flutter UI as before. Captured native screens honor your app-wide maskAllTexts/maskAllImages settings; setting them false reveals native text/images too, including native input fields.

  Not captured:

  • Partial-height sheets (Apple Pay, share sheet, .pageSheet/.formSheet modals)
  • Content rendered by another process (Apple Pay, photo picker) — blank if the surrounding screen is captured
  • Android: anything that is not a full activity in your app's process (Chrome Custom Tabs, Google Pay, dialogs, bottom sheets, permission prompts)
  • iOS: covers without an opaque background (camera previews, image/blur backdrops)

  Screens that are not captured keep the previous behavior: replay keeps showing the covered Flutter UI.

  The flag can also be toggled at runtime. Turning it off takes effect immediately: toggling off right before presenting a sensitive native screen guarantees that screen is not captured. Enable it before presenting a screen you want captured — enabling while a native screen is already up may not capture that screen.

  Requires posthog-ios >= 3.66.0 and posthog-android >= 3.55.0 (resolved automatically by the bundled dependency ranges).

Patch Changes

• 22dbde4: Android: session replay screenshots are now timestamped with the native SDK's clock instead of the system clock. The two can diverge (the SDK prefers the network-time clock on API 33+), which scrambled the replay timeline — frames appeared at a different time than touch events and native-captured screens.

Minor Changes

• db486b0: Add a bootstrap option to PostHogConfig for pre-seeding identity and feature flags before the first /flags response. Set config.bootstrap = PostHogBootstrapConfig(...) before setup() so early events carry a caller-controlled distinct ID and flag reads return your values during cold start. The values are forwarded to the native iOS and Android SDKs and mirror the bootstrap option in posthog-js. On Flutter web, configure bootstrap in your posthog.init call instead.

Patch Changes

• d4c7fb8: Require posthog-android 3.54.1 or newer. Earlier 3.x versions performed replay work on every touch (a network-time Binder call, a MotionEvent copy, and a replay-executor submission) even when session replay was disabled or sampled out, which could cause ANRs on Android. Projects with a Gradle lockfile or cached dependency resolution could stay pinned to an affected version; the raised floor guarantees the fixed SDK.

Minor Changes

• b851632: Improve error-tracking cause handling: captureException now walks an error's cause chain (AsyncError, all enumerable ParallelWaitError failures, and exceptions exposing a cause getter) into multiple $exception_list items, outermost-first (wrapper first, root cause last), with a cycle guard and a depth cap of 10.

Minor Changes

• de7b5e8: Platform views are now masked by default in session replay (they now appear as a black box). Use maskAllPlatformViews = false to disable masking globally, or wrap individual views in PostHogPlatformView(privacy: PostHogPlatformViewPrivacy.capture) to reveal them selectively.

Minor Changes

• 3fe9ab2: Add addExceptionStep, recording breadcrumb-style context records that attach to every captured $exception as $exception_steps, giving the error-tracking UI a timeline of recent activity leading up to each error.

  Steps accumulate in a rolling, byte-bounded buffer owned by the embedded native SDK, so they also survive native fatal crashes and attach to the crash $exception reported on the next launch. The buffer rotates only by byte-budget eviction and is not cleared by a capture or an identity change. Configure it on config.errorTrackingConfig.exceptionSteps (enabled, maxBytes).

  Posthog().addExceptionStep('User tapped Checkout', properties: {'screen': 'cart'});
  

  Requires posthog-android and posthog-ios versions that support exception steps. On web, steps are forwarded to posthog-js, and exceptions captured via captureException now route through posthog-js's captureException (instead of a generic $exception capture) so steps and other required metadata attach.

Minor Changes

• 647d48b: Add structured logging. Send logs to PostHog from your Flutter app and see them next to your events and session replays.

  Posthog().logger.info('checkout completed', {'order_id': 'ord_789'});
  Posthog().logger.error('payment failed', {'error_code': 'E001'});
  
  // Or pick the level at runtime:
  await Posthog().captureLog(body: 'request finished', level: PostHogLogSeverity.warn);
  

  Levels: trace, debug, info, warn, error, fatal. Configure service identity, redaction (beforeSend), and batching/rate-cap tuning on config.logsConfig — all optional, with sensible native defaults. Works on iOS, Android, and web.

  Requires posthog-android 3.48.0 or newer.

  See https://posthog.com/docs/logs for details.

Minor Changes

• 4749dd4: Add setPersonPropertiesForFlags, resetPersonPropertiesForFlags, setGroupPropertiesForFlags, and resetGroupPropertiesForFlags, bringing the Flutter SDK to parity with the native iOS/Android and JS SDKs.

  These set person/group properties that are sent inline with the next feature flag evaluation request, so flags targeting those properties can be evaluated immediately — without enqueuing a $set event or waiting for it to be ingested into the person store. By default they reload feature flags and the returned Future completes only after the reload finishes, so the next getFeatureFlag/getFeatureFlagResult reflects the updated properties. Pass reloadFeatureFlags: false to skip the reload.

  await Posthog().setPersonPropertiesForFlags({
    "storefront_country": "US",
    "superwall_demand_score": 88,
  });
  final result = await Posthog().getFeatureFlagResult("my_flag");
  

Patch Changes

• 7077816: reloadFeatureFlags() now resolves its Future only after feature flags have finished loading, instead of returning immediately. await Posthog().reloadFeatureFlags() is now reliable, so reading a flag (or starting session recording) right after a reload sees the up-to-date result.

Patch Changes

• 2c0925e: Fix link-type survey questions with no URL silently failing to render on Android. The deserializer now treats a missing link as an empty string instead of throwing on null.

Patch Changes

• 06b1569: Skip Flutter SDK setup for blank project tokens before storing config or installing Dart integrations.

Minor Changes

• cfcab97: Support Android builds with AGP 9 built-in Kotlin while preserving compatibility with AGP 8. This release requires Android Gradle Plugin 8.0 or newer.

Patch Changes

• f9490ed: Raise the minimum posthog-android version to 3.44.0 to guarantee session replay minimum recording duration support.

Patch Changes

• 5c60fb5: Reinstall Flutter error autocapture handlers when re-enabling data collection.

Patch Changes

• 0d4ab6e: Prefer projectToken when configuring PostHog on Darwin platforms.

Minor Changes

• 4e3fa7b: Rename apiKey to projectToken with backward-compatible aliases

Patch Changes

• 04535db: Trim surrounding whitespace from API keys and host config before passing them to the native SDKs.

Patch Changes

• e9e94d1: Accept Map args in the web session recording start handler
• b55480e: Avoid retaining raw RGBA bytes for session replay diffing
• 4bbfb38: Reduce session replay frame callback overhead
• 3bc8c50: Cancel in-flight session replay screenshot capture when stopping
• 0bdb58c: Prevent overlapping session replay snapshot captures
• d4dcbbe: Dispose native session replay resources on screenshot errors

Patch Changes

• b4532f5: fix: suppress ghost screen events when app is in background
• ac2b568: chore: bump posthog-ios dependency to 3.50.0 for error tracking GA

Minor Changes

• 5e31246: Enable captureApplicationLifecycleEvents by default and align Android config key name.

  Application lifecycle events (Application Opened, Application Backgrounded, etc.) are now captured by default. If you don't want these events, you can disable them:

  • Dart (recommended): Set config.captureApplicationLifecycleEvents = false in your PostHog configuration.
  • Android (manifest): Add <meta-data android:name="com.posthog.posthog.CAPTURE_APPLICATION_LIFECYCLE_EVENTS" android:value="false" /> to your AndroidManifest.xml. The legacy key com.posthog.posthog.TRACK_APPLICATION_LIFECYCLE_EVENTS is still supported.
  • iOS/macOS (Info.plist): Set com.posthog.posthog.CAPTURE_APPLICATION_LIFECYCLE_EVENTS to NO in your Info.plist.

Minor Changes

• ca19677: Add native exception capture support for Apple platforms (iOS, macOS, tvOS)

Patch Changes

• 85d0d6a: fix: PostHogMaskWidget mask appearing at screen origin

Minor Changes

• 81a5883: Web: Override SDK info via _overrideSDKInfo and set location properties on capture events

Patch Changes

• 259ef67: Web: Fix dartify cast error in chunk_ids_web.dart for error tracking

Minor Changes

• bba1d83: bump native sdk versions to support survey event property filters

Minor Changes

• 8f6b291: Add Swift Package Manager support for iOS and macOS

Minor Changes

• 12a378f: feat(surveys): support survey schedule 'always' to show every time and survey wait period filtering (seenSurveyWaitPeriodInDays)

Patch Changes

• e4b9224: fix: bump iOS SDK minimum to 3.43.0 to fix feature flags race condition between preload and identify

Minor Changes

• 6d13370: Breaking: Minimum Dart SDK version is now 3.6.0 and minimum Flutter version is now 3.27.0. Migrate to pub workspace structure.

Minor Changes

• e703672: feat: add sampleRate support

Patch Changes

• 541b280: fix: textfield masking and element transform positioning in session replay

Patch Changes

• c7dcd9c: test new release process, again

Patch Changes

• f7801dc: test new release process

• fix: add explicit package:meta/meta.dart import for @internal annotation (#286)
• feat: add setPersonProperties method to set person properties without requiring identify (#284)
• fix: add filled: false to survey open-text questions to prevent app theme from overriding survey customization values (#285)

• feat: add manual session recording control APIs (#256)
  • startSessionRecording({bool resumeCurrent = true}) Start session recording, optionally starting a new session
  • stopSessionRecording() Stop the current session recording
  • isSessionReplayActive() Check if session replay is currently active
• feat: add getFeatureFlagResult API (#279)

• chore: add support for thumbs up/down surveys (#257)

• perf: Optimize Screenshot diff check (#271)

• chore: improve survey color handling (#233)

• feat: add beforeSend callback to PostHogConfig for dropping or modifying events before they are sent to PostHog (#255)

  • Limitation:
    • Does NOT intercept native-initiated events such as:
      • Session replay events ($snapshot) when config.sessionReplay is enabled
      • Application lifecycle events (Application Opened, etc.) when config.captureApplicationLifecycleEvents is enabled
      • Feature flag events ($feature_flag_called) when config.sendFeatureFlagEvents is enabled
      • Identity events ($set) when identify is called
      • Survey events (survey shown, etc.) when config.surveys is enabled
    • Only user-provided properties are available; system properties (like $device_type, $session_id) are added by the native SDK at a later stage.

• perf: Optimize mask widget rect collection to O(N) (#269)

• feat: flutter error tracking support for web (#243)
• feat: add userProperties and userPropertiesSetOnce parameters to capture() method (#254)

• fix: RichText, SelectableText, TextField labels and hints not being masked in session replay (#251)

• chore: update languageVersion and apiVersion from 1.8 to 2.0 on Android to be compatible with Kotlin 2.3 (#245)

• feat: Add onFeatureFlags callback to PostHogConfig to get notified when feature flags are loaded. Use Posthog().getFeatureFlag() or Posthog().isFeatureEnabled() within the callback to access fresh flag values. (#224)

• fix: TextFormField widgets were not being masked (#227)

• feat: add autocapture exceptions (#214)
  • Limitations:
    • No Flutter web support
    • No native iOS exception capture
    • No native C/C++ exception capture on Android (Java/Kotlin only)
    • No stacktrace demangling for obfuscated builds (--obfuscate and --split-debug-info) for Dart code and isMinifyEnabled for Java/Kotlin code
    • No source code context
    • No background isolate error capture

• feat: surveys GA (#215)

  Note: Surveys are now enabled by default.

• feat: add manual error capture (#212)
  • Note: The following features are not yet supported:
    • Automatic exception capture
    • De-obfuscating stacktraces from obfuscated builds (--obfuscate and --split-debug-info)
    • Source code context 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)