posthog_flutter

Patch Changes

• 033c2ce: Stop exporting PostHogWidgetState and PostHogMaskWidgetState, which are internal to PostHogWidget and PostHogMaskWidget and have no usable public members

Patch Changes

• e0a5f8f: Deprecate PostHogDataMode.cellular, which always behaved like PostHogDataMode.any; use any instead.

Patch Changes

• b064e83: Show a survey that arrives before PosthogObserver has a context once the next navigation happens, instead of dropping it and blocking later surveys.

Patch Changes

• cadba6d: Reapply Dart automatic error-capture hooks when setup is called again with changed flags.

Patch Changes

• 890e432: Parse survey question id from native payloads instead of using the question type.

Patch Changes

• 56293ae: Preserve chained error handlers after teardown and prevent duplicate exception captures when error tracking restarts.

Patch Changes

• 66c9257: Stop calling the deprecated getFeatureFlagPayload of the PostHog iOS SDK on iOS and macOS, which is removed in its next major version.

Patch Changes

• a5ce763: Correct in-app error tracking configuration examples to use bare Dart package names.
• 2bd9632: Fix session replay keeping the original screen size after the app's window is resized, such as when it rotates or a foldable is folded or unfolded.

Patch Changes

• afc14aa: Let optional open-text and rating survey questions be skipped, and use the question's button label.

Patch Changes

• 99075ad: Close a completed survey immediately when its appearance turns the thank-you screen off.

Patch Changes

• 9b6fb05: Record a skipped optional multiple-choice survey question as no answer instead of an empty list.
• 0ebaae9: Use the screen name argument when properties also contain $screen_name.

Patch Changes

• 4d5268d: Retry a session replay snapshot on iOS when it fails to encode, instead of dropping it.

Patch Changes

• 2f164dd: Retry a session replay snapshot when the native channel call fails instead of marking it delivered.

Patch Changes

• 06a40c2: Keep legacy $set and $set_once person properties when the nested map comes from JSON.

Patch Changes

• a71971e: Run beforeSend for capture, screen, and captureException on Flutter web.

Minor Changes

• 9803604: Attach $app_version and $app_build to web events, read from the FLUTTER_BUILD_NAME / FLUTTER_BUILD_NUMBER compile-time constants (Flutter 3.47+), so web events carry the running app's version like iOS and Android do.

Minor Changes

• fbe5397: Add the compression config (PostHogCompression.gzip / none) so an app can send request bodies uncompressed, e.g. when a managed network or work profile alters the compressed body in transit.

Minor Changes

• b155321: Support survey partial responses and persistent resume on iOS and Android. Submitted answers and the next question are restored after SDK recreation, while completing or dismissing a survey, or calling reset, clears saved progress. Requires PostHog iOS >= 3.80.0 and Android >= 3.70.0.

  Fix skipping optional answers on Android, which could previously fail when the response was null.

Minor Changes

• 36fcf5a: Add $recording_status and $sdk_debug_* session replay debug properties to captured events via the native SDKs, forward throttleDelay to the native replay config, and raise the native floors to posthog-ios 3.80.0 and posthog-android 3.69.0

Minor Changes

• 39bd554: Add sessionReplayConfig.textMaskPolicy to mask text at glyph precision instead of all-or-nothing. A policy is a PostHogTextMask Function(String text, Widget widget) that decides per text node whether to mask all of it, none of it, only some character ranges, or everything except some ranges — using the node's rendered string, the widget that produced it, or both — so an app can hide amounts and card numbers while the labels around them stay readable. Ships with PostHogTextMaskPolicies.digits(), .redact(RegExp) and .reveal(RegExp). Applies to Text, RichText, and non-sensitive text inputs; sensitive inputs, PostHogMaskWidget, and PostHogUnmaskWidget keep precedence, and the policy fails closed by masking the whole node when it throws or returns a range outside the text.

Minor Changes

• 7f660c8: Support automatic submission for survey ratings and single-choice questions without an open choice when skipSubmitButton is enabled. Requires PostHog iOS 3.77.0 and Android 3.66.4 or newer.

Patch Changes

• 3cfa388: Document that on iOS maskAllPlatformViews = false and PostHogPlatformViewPrivacy.capture only reveal WKWebView-backed UiKitViews (maps and other native views stay masked), and log in debug builds when the native side declines a platform view capture and the view is masked instead (#593).

Patch Changes

• 8a27e44: Render multiple-choice option labels in the survey text color so they stay readable on dark backgrounds.

Patch Changes

• 2e343e6: Respect configured open-text survey placeholders and leave unset placeholders empty.

Patch Changes

• 5f92452: Honor shuffleOptions in Flutter surveys while keeping Other last and choice order stable while answering.

Minor Changes

• 0552616: Add experimental Android session replay screenshot controls: screenshotScale and screenshotCompressionQuality for Flutter and native captures, and screenshotColorMode for native captures. Scale Flutter captures, masks, and embedded native views together while preserving logical playback dimensions and JPEG encoding.

Patch Changes

• 77c4fe0: Fix a manual capturePushNotificationOpened() call double-counting a PostHog notification tap the SDK already captured, using the dedupe added in posthog-android 3.65.0 and posthog-ios 3.75.0. Update the native SDKs to posthog-android 3.65.2 and posthog-ios 3.75.2.

Minor Changes

• aa1dea6: Add PostHogUnmaskWidget to reveal known-safe Flutter text and images while keeping global masking enabled. Unmasking overrides explicit masks in either nesting order, but sensitive inputs stay masked. Protection covers obscured fields, sensitive keyboard types, and standard autofill hints for personal, contact, address, authentication, and payment data across Material, Cupertino, and direct EditableText inputs. Nested unmask regions are subtracted from enclosing masks only when their transforms and clips allow a safe rectangular exclusion. On Flutter web, mounting either wrapper enables canvas masking; declare canvasCapture.maskRegionsFn: () => null in posthog.init's session_recording configuration to protect frames before the first mount. Native platform views and captured native screens are unaffected.

Patch Changes

• 660270b: Fix $push_notification_opened being lost on Android when a notification tap reaches the app before Posthog().setup() runs.

Minor Changes

• 66e738c: Add sessionReplayConfig.maskCustomPaint, defaulting to false, to opt into masking the full bounds of custom-painted widgets independently of text and image masking.

  Flutter's maskAllTexts and maskAllImages inspect the widget tree, not arbitrary canvas drawing. Even with those flags enabled, custom-painted text and images require maskCustomPaint or an explicit PostHogMaskWidget. The new option stays opt-in because it can also mask non-sensitive Material UI, including tab bars, checkboxes, switches, and progress indicators.

  Framework scrollbar-only painters are excluded so desktop scrollable viewports remain visible, while their children are still checked for masks. With maskCustomPaint enabled, frames containing painters with unknown bounds, including zero-sized painters, are skipped rather than sent unmasked.

Patch Changes

• 696ab7f: Warn when PostHogWidget mounts before Posthog().setup() on mobile, explaining that session replay requires setup before mounting or remounting the widget after setup.

Minor Changes

• dddc307: Add sessionReplayConfig.captureTouches to disable replay touch coordinates during SDK initialization on Android and iOS while keeping masked screenshots. This protects keypad entry whose values can be reconstructed from tap positions. Requires posthog-android 3.64.0 and posthog-ios 3.74.0. Runtime changes are not supported.

Patch Changes

• 3ce8592: Fix session replay masking only the first line of an auto-growing text field (maxLines: null or expands: true); the mask now covers the field's full height.

Minor Changes

• 00337ab: Capture $push_notification_opened on Android for every notification tap, both on a cold launch and while the app is already running. Remove any manual capturePushNotificationOpened call wired to FirebaseMessaging.onMessageOpenedApp or getInitialMessage() — that tap is now captured automatically and the manual call is not deduplicated against it. Requires posthog-android 3.62.0.

Patch Changes

• 00337ab: Fix $push_notification_opened not being captured on iOS when the app is cold-launched from a notification tap. Requires posthog-ios 3.72.0, and your app must set UNUserNotificationCenter.current().delegate — without one iOS reports the tap to nobody.
• 00337ab: Change com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_OPENED to also suppress the new iOS cold-start prewarm in apps that do not use com.posthog.posthog.AUTO_INIT.

Minor Changes

• d7c51c2: Surveys can now display an optional intro screen before the first question, configured via the new displayIntroScreen, introScreenHeader, introScreenDescription, introScreenDescriptionContentType, and introScreenButtonText appearance fields. The intro is rendered by the Dart survey UI as the leading mirror of the confirmation message: advancing past it records no response and sends no survey event, while closing the survey from the intro still sends the normal survey dismissed event. Requires posthog-ios >= 3.70.0 and posthog-android >= 3.59.0, which forward the new appearance fields over the bridge.

Patch Changes

• e7445f4: Fix session replay painting a clipped map, WebView, or camera preview past its visible edge and over the widgets around it. A platform view's mask now covers only the part an ancestor clip leaves visible, and a revealed one is clipped to the same region, so widgets a platform view used to bury are visible in replays again

Minor Changes

• 0de477b: Add PostHogSessionReplayConfig.verifyScreenshotMaskAlignment for Android native screens captured with captureNativeScreens. Enabling it can preserve screenshots and mask alignment during pixel-only redraws, including continuously animated content, but performs additional view hierarchy walks. It remains disabled by default.

Patch Changes

• 577c59e: Fix session replay started with startSessionRecording() capturing nothing on Android by requiring posthog-android 3.60.7 or newer.

Minor Changes

• 024d690: Add errorTrackingConfig.captureNativeCrashes to capture native C/C++ (NDK) crashes on Android. Requires Android 12 (API 31) and exception autocapture enabled in the project's error tracking settings; crashes are captured on the next app launch and symbolicated against .so debug symbols uploaded with the PostHog Gradle plugin.

Patch Changes

• f21daf7: Fix session replay recording the Flutter UI from underneath a native screen when the session changes — reset(), or a close()/setup() pair — while that screen is up.

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

• 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

• 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.

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

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.