PostHog Flutter SDK
Getting started
The Flutter SDK runs in iOS, Android, macOS, and web apps.
To send your first event, add posthog_flutter, then call setup once before runApp with your project token and host from your project settings.
Use capture for your own events, and call flush and close before the app exits.
Install the package:
Initialize the SDK once, before runApp, with your project token and host:
Capture an event and identify the user:
Flush queued events and shut the SDK down before the app exits:
Setup
Posthog.setup
Initializes the PostHog SDK.
This method sets up the connection to your PostHog instance and prepares the SDK for tracking events and feature flags.
The config object contains your project token, host, and other settings.
To listen for feature flag load events, provide an onFeatureFlags
callback in the PostHogConfig.
Repeated setup reapplies Dart-side settings such as the error-tracking hooks. Most native settings still require close before setup because the native SDKs ignore repeated setup.
Returns a Future that completes when platform setup has finished.
Example:
For Android and iOS, if you are performing a manual setup,
ensure com.posthog.posthog.AUTO_INIT: false is set in your native
configuration.
Capture
Posthog.capture
Captures a custom event.
Docs: https://posthog.com/docs/product-analytics/user-properties
We recommend using an [object] [verb] format for eventName, where the
object is the entity that the behavior relates to and the verb is the
behavior itself. For example: project created, user signed up, or
invite sent.
The optional properties are event properties.
The optional userProperties are person properties set with $set.
The optional userPropertiesSetOnce are person properties set with
$set_once.
Returns a Future that completes when the event has been queued.
Example
Identify
Posthog.identify
Associates events with a specific user.
The userId is a unique identifier for your user, typically their email or
database ID.
The optional userProperties are person properties set with $set.
The optional userPropertiesSetOnce are person properties set with
$set_once.
Returns a Future that completes when the identify call has been queued.
Note that identifying a user reloads feature flags, which issues a
/flags request even when PostHogConfig.preloadFeatureFlags is false.
Example:
Logs
Posthog.captureLog
Captures a structured log record.
Docs: https://posthog.com/docs/logs
captureLog is not gated by remote config.
The body is the log message. A blank body is dropped before
PostHogLogsConfig.beforeSend runs.
The optional level is the severity, defaulting to
PostHogLogSeverity.info.
The optional attributes are per-record attributes (e.g. request id,
duration). Values must be supported by the platform channel serializer.
The optional traceId, spanId, and traceFlags are W3C distributed
tracing fields used to correlate a log with a trace. traceId is a
32-character lowercase hex string, spanId is 16 characters, and
traceFlags is a bitfield whose bit 0 is the sampled flag (an explicit
0 is emitted; null omits the field). They pass through unchanged and
are not visible to PostHogLogsConfig.beforeSend.
Auto-captured context (distinct id, session id, screen name, app state, active feature flags) is added by the native SDK.
Records are passed through PostHogLogsConfig.beforeSend before being forwarded to the native SDK; a callback may modify or drop them.
Returns a Future that completes when the record has been forwarded.
Windows/Linux: not supported.
Example:
Posthog.logger
Per-level logger facade for capturing structured logs.
Each helper delegates to captureLog with the matching severity. Built once on first access and cached.
Example:
Alias
Posthog.alias
Creates an alias for the current user.
The alias is the additional distinct ID to associate with the user.
Returns a Future that completes when the alias call has been queued.
Capture exception
Posthog.captureException
Captures an exception with optional custom properties.
The error is the error or exception to capture.
The optional stackTrace is attached to the exception. If omitted, the
current stack trace is used by the exception processor where possible.
The optional properties are added to the $exception event.
Returns a Future that completes when the exception event has been queued.
Posthog.captureRunZonedGuardedError
Captures a runZonedGuarded error with optional custom properties.
See: https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html
The error is the error or exception received by runZonedGuarded.
The optional stackTrace is attached to the exception. If omitted, the
current stack trace is used by the exception processor where possible.
The optional properties are added to the $exception event.
Returns a Future that completes when the exception event has been queued.
Debug
Posthog.debug
Enables or disables verbose logs about the inner workings of the SDK.
Set enabled to true to enable debug logs, or false to disable them.
Returns a Future that completes when the debug setting has been applied.
Exception steps
Posthog.addExceptionStep
Records an exception step (breadcrumb-style context record).
Steps accumulate in a rolling, byte-bounded buffer and are attached to
every captured $exception event as $exception_steps, giving the
PostHog error-tracking UI a timeline of recent activity leading up to each
error. The buffer rotates only by byte-budget eviction (see
PostHogExceptionStepsConfig.maxBytes) and is not cleared by a capture or
an identity change.
The buffer is owned by the embedded native SDK, so steps also survive
native fatal crashes and attach to the crash $exception reported on the
next launch.
The message is a short, non-empty description of what happened; an empty
or whitespace-only message is ignored. The optional properties are
additional context. The reserved keys $message and $timestamp are
stripped — the SDK sets the canonical values, including a timestamp
captured when the step is recorded.
Recording never throws into your app and does not block the caller.
Note:
- Flutter web: forwarded to posthog-js. Steps attach to exceptions captured by posthog-js, but not to exceptions captured via captureException on web.
- Windows/Linux: the buffer is kept in memory by the Dart implementation, and no native crashes are captured on desktop.
Example:
Flush
Posthog.flush
Flushes queued events immediately where supported by the platform.
Returns a Future that completes when the flush request has finished.
Get distinct ID
Posthog.getDistinctId
Returns the registered distinctId property.
Returns an empty string if the platform cannot provide a distinct ID.
Get feature flag
Posthog.getFeatureFlag
Returns the feature flag value for key.
Returns null if the flag does not exist or cannot be loaded. For boolean
flags, returns true or false. For multivariate flags, returns the
variant key.
sendFeatureFlagEvent controls whether this call captures the
$feature_flag_called event. Defaults to null, which follows
PostHogConfig.sendFeatureFlagEvent. Pass false to skip the event for
this call, or true to capture it even when the config turns it off.
Example:
Get feature flag payload
Posthog.getFeatureFlagPayload
Returns the payload for the feature flag key.
Returns null when the flag does not exist, has no payload, or the payload
cannot be loaded.
Get feature flag result
Posthog.getFeatureFlagResult
Returns the full feature flag result for key, including value and
payload.
This is the canonical method for getting feature flag data.
Returns null if the flag does not exist or cannot be loaded.
Set sendEvent to false to suppress the $feature_flag_called event.
This is useful when you only need the payload and do not want to emit the
event.
Example:
Get feature flags
Posthog.getAllFeatureFlags
Returns the results of all currently loaded feature flags.
Each PostHogFeatureFlagResult carries the flag's key, enabled state,
variant (for multivariate flags), and payload. This reads the flags from
the last load without a network request; call reloadFeatureFlags first
to refresh them. Unlike getFeatureFlag, it never captures the
$feature_flag_called event.
Returns null when no flags have been loaded yet or the SDK is disabled.
On web, posthog-js returns an empty list before flags load, and this
returns null when the loaded posthog-js predates getAllFeatureFlags
(1.395.0).
Example:
Get session ID
Posthog.getSessionId
Returns the session ID if a session is active.
Returns null when no session is active or the platform cannot provide a
session ID.
Group
Posthog.group
Associates the current user with a group.
Docs: https://posthog.com/docs/product-analytics/group-analytics
The groupType is the group type, such as company.
The groupKey is the unique key for the group.
The optional groupProperties are group properties set with $group_set.
Returns a Future that completes when the group call has been queued.
Note that setting a group reloads feature flags, which issues a /flags
request even when PostHogConfig.preloadFeatureFlags is false.
Example:
Is feature enabled
Posthog.isFeatureEnabled
Returns whether a boolean feature flag is enabled.
Docs: https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
The key is the feature flag key.
sendFeatureFlagEvent controls whether this call captures the
$feature_flag_called event. Defaults to null, which follows
PostHogConfig.sendFeatureFlagEvent. Pass false to skip the event for
this call, or true to capture it even when the config turns it off.
Returns false when the flag is disabled, missing, or not a boolean flag.
Example:
Is opt out
Posthog.isOptOut
Returns whether the current user has opted out of data collection.
Is session replay active
Posthog.isSessionReplayActive
Returns whether session replay is currently active.
Returns false when session replay is inactive or unsupported by the
current platform.
Windows/Linux: not supported.
Opt in
Posthog.optIn
Opts the current user back in to data collection.
Reinstalls Flutter error autocapture. If optOut stopped session replay, this starts a new recording.
Returns a Future that completes when the opt-in request has been queued.
Register
Posthog.register
Registers a super property sent with all following events.
The property remains active until unregister is called with the same
key. The value must be supported by the platform channel serializer.
Returns a Future that completes when the property has been registered.
Reload feature flags
Posthog.reloadFeatureFlags
Reloads feature flags for the current user.
Returns a Future that completes when the reload request has been queued.
Reset
Posthog.reset
Resets all cached properties including the distinctId.
The SDK will behave as if it has been setup for the first time.
Returns a Future that completes when the reset request has been queued.
Reset group properties for flags
Posthog.resetGroupPropertiesForFlags
Clears group properties that were set for feature flag evaluation via setGroupPropertiesForFlags.
If groupType is provided, only properties for that group type are
cleared; otherwise all group properties are cleared.
Set reloadFeatureFlags to false to skip reloading flags after clearing
the properties (defaults to true). When true, the returned Future
awaits the reload before completing (on iOS/Android, after flags finish
loading; on web, best-effort).
Reset person properties for flags
Posthog.resetPersonPropertiesForFlags
Clears all person properties that were set for feature flag evaluation via setPersonPropertiesForFlags.
Set reloadFeatureFlags to false to skip reloading flags after clearing
the properties (defaults to true). When true, the returned Future
awaits the reload before completing (on iOS/Android, after flags finish
loading; on web, best-effort).
Screen
Posthog.screen
Captures a screen view event.
The screenName is the screen title or route name.
The optional properties are additional screen event properties.
Returns a Future that completes when the screen event has been queued.
Set group properties for flags
Posthog.setGroupPropertiesForFlags
Sets properties for a specific groupType that are used only for feature
flag evaluation.
The properties are sent inline with the next feature flag evaluation request, so flags that target group properties can be evaluated without waiting for ingestion.
The groupProperties are merged with any previously set values for the
same groupType; matching keys are overwritten. If groupProperties is
empty, this is a no-op.
Set reloadFeatureFlags to false to skip reloading flags after updating
the properties (defaults to true). When true, the returned Future
awaits the reload before completing (on iOS/Android, after flags finish
loading; on web, best-effort).
Example:
Set person properties
Posthog.setPersonProperties
Sets person properties for the current user without requiring identify.
This method sends person property updates without changing the current distinct ID.
The optional userPropertiesToSet values are set with $set and overwrite
existing values.
The optional userPropertiesToSetOnce values are set with $set_once and
do not overwrite existing values.
Returns a Future that completes when the update has been queued. If both property maps are null or empty, no event is queued.
Example:
Set person properties for flags
Posthog.setPersonPropertiesForFlags
Sets person properties that are used only for feature flag evaluation.
Docs: https://posthog.com/docs/feature-flags
Unlike setPersonProperties, this does not enqueue a $set event. The
properties are sent inline with the next feature flag evaluation request,
so flags that target these properties can be evaluated immediately without
waiting for the $set event to be ingested into the person store.
The userProperties are merged with any previously set values; matching
keys are overwritten. If userProperties is empty, this is a no-op.
Set reloadFeatureFlags to false to skip reloading flags after updating
the properties (defaults to true). When true, the returned Future
awaits the reload before completing; on iOS and Android this means flags
have finished loading, so the next getFeatureFlag / getFeatureFlagResult
reflects the updated properties. On web the reload is best-effort.
Example:
Shutdown
Posthog.close
Closes the PostHog SDK and cleans up resources.
This is also the entry point for reconfiguring: the native SDKs ignore a repeated setup, so changing the project token, host, or native session replay settings means calling close first and then setup again.
Whatever session replay records after the next setup starts as a fresh recording. Whether the platform also changes the session here differs by platform, so do not rely on a close/setup pair rotating the session id.
Returns a Future that completes when platform resources have been closed.
Windows/Linux: first makes one attempt to send the queued events and waits for it for up to two seconds. Events left unsent go out with the next setup, or are lost when the application support directory is unavailable and state is kept in memory.
Note: After calling close(), surveys will not be rendered until the
SDK is re-initialized and the next navigation event occurs.
Start session recording
Posthog.startSessionRecording
Starts session recording.
This method will have no effect if PostHog is not enabled, or if session replay is disabled in your project settings.
Set resumeCurrent to true (the default) to resume recording the current
session. Set it to false to start a new session and begin recording —
though a new session is not guaranteed while recording is already active,
so call stopSessionRecording first if you need one. Either way, false
restarts the recording even when the platform keeps the current session id.
Returns a Future that completes when the start request has been sent.
Windows/Linux: not supported.
Stop session recording
Posthog.stopSessionRecording
Stops the current session recording if one is in progress.
This method will have no effect if PostHog is not enabled.
Returns a Future that completes when the stop request has been sent.
Windows/Linux: not supported.
Unregister
Posthog.unregister
Unregisters a previously registered super property.
The key identifies the property to stop sending with future events.
Returns a Future that completes when the property has been removed.
SDK utils
Posthog.Posthog.new
Returns the singleton PostHog client instance.
Posthog.captureFeatureInteraction
Captures a $feature_interaction event when the user interacts with the
feature behind the feature flag flag.
The event carries feature_flag and, for multivariate flags,
feature_flag_variant, and sets the person property
$feature_interaction/<flag> to the variant.
flagVariant defaults to null, which uses the flag's current value
without capturing $feature_flag_called. When the flag has no value
(not loaded or unknown), Android falls back to true, while iOS, macOS,
web, Windows, and Linux skip the event.
Example:
Posthog.captureFeatureView
Captures a $feature_view event when the user sees the feature behind
the feature flag flag.
The event carries feature_flag and, for multivariate flags,
feature_flag_variant, and sets the person property
$feature_view/<flag> to the variant.
flagVariant defaults to null, which uses the flag's current value
without capturing $feature_flag_called. When the flag has no value
(not loaded or unknown), Android falls back to true, while iOS, macOS,
web, Windows, and Linux skip the event.
Example:
Posthog.capturePushNotificationOpened
Captures $push_notification_opened when a user opens a push
notification.
Call this only for opens PostHogConfig.capturePushNotificationOpened cannot see itself — local notifications on either platform, notifications you display yourself from a foreground message, and push delivered outside FCM on Android. That doc has the full coverage matrix.
Do not wire this to FirebaseMessaging.onMessageOpenedApp or
getInitialMessage(): the SDK already captures those taps. On both
platforms a second report of a PostHog-sent notification within 5 minutes
of the first is skipped; an open of a push PostHog did not send carries
nothing to match on, so it is counted twice.
That dedupe also means a manual call cannot enrich an automatic capture.
The Android tray intent carries no notification text, so its automatic
event has no $notification_title or $notification_body, and
re-reporting the tap with them is skipped rather than merged.
The event is built natively, so PostHogConfig.beforeSend callbacks do not run on it — redact anything sensitive before passing it here.
Keys of payload's posthog entry become $notification_<key>
properties; it is decoded natively whether it arrives as a map or as a
JSON string. Leave action null for a plain tap — only action-button
taps carry an identifier.
subtitle is iOS only and ignored on Android, which has no such field.
Not supported on Flutter web, Windows or Linux.
Posthog.disable
Opts the current user out of data collection.
Posthog.enable
Opts the current user back in to data collection.
Posthog.optOut
Opts the current user out of data collection.
Also stops session replay and uninstalls Flutter error autocapture.
Returns a Future that completes when the opt-out request has been queued.
Posthog.registerPushNotificationToken
Registers this device's push token or Firebase Installation ID (FID) so PostHog Workflows can target it.
Both platforms register automatically at startup when PostHogConfig.capturePushNotificationSubscriptions is enabled, so the main reason to call this is a later Firebase registration or token refresh, which that startup fetch cannot see.
appId identifies the app the identifier belongs to: the Firebase
project_id for an FCM token or FID, the APNs bundle id for an APNs token.
It tells PostHog which provider to deliver through — the platform is
only recorded alongside it. Leave it null and iOS falls back to the
bundle id while Android falls back to the default FirebaseApp's project
id, so pass it explicitly if your app does not use Firebase or registers
for a non-default Firebase project. Android cannot register without one
and reports the skip as a PlatformException, logged in debug builds.
The default is APNs on iOS and FCM on Android, matching what
PostHogConfig.capturePushNotificationSubscriptions registers on its own.
On Android, enabling firebase_messaging_installation_id_enabled in the
app's manifest switches automatic registration to FIDs. Pass the FID to
this method unchanged; no identifier type parameter is needed.
With firebase_messaging 17+, enable that manifest flag and forward
onRegistered after setup completes, then register with Firebase:
On Android, explicit calls refresh the subscription even when the FID
hasn't changed; automatic startup registration still deduplicates it.
For older firebase_messaging versions, forward onTokenRefresh instead
and leave FID mode disabled. Neither Firebase callback should be forwarded
unguarded on iOS: pairing a Firebase identifier with the default APNs
bundle id causes delivery to fail.
Using FCM on both platforms is supported — pass the Firebase
project_id as appId on iOS too — but you must set
PostHogConfig.capturePushNotificationSubscriptions to false first.
PostHog stores one subscription per app id, so leaving automatic
registration on gives an iOS device two: an APNs one under the bundle id
and an FCM one under the project id. A Workflow configured with both
integrations then delivers to that device twice, and
unregisterPushNotificationToken only clears the most recently registered
of the two.
Registration also fails server-side if your PostHog project has no
Firebase or APNs integration configured for appId.
Call this only after setup has completed: the native SDKs silently drop a token registered before they are initialized, and this method still completes without an error.
Not supported on Flutter web, macOS, Windows or Linux.
Posthog.unregisterPushNotificationToken
Unregisters this device's push token so Workflows stop targeting it — for example from your logout flow.
The intent is durable: if the request fails or the device is offline, the native SDK retries it on the next flush or app launch. reset already moves a registered token to the new anonymous identity on its own, so this is only needed when you manage subscriptions yourself.
Not supported on Flutter web, macOS, Windows or Linux.
PostHogIsolateExtension
PostHogIsolateExtension
Forwards uncaught errors from an isolate to PostHog.
PostHogIsolateExtension.addPostHogErrorListener
Captures this isolate's uncaught errors using Posthog.captureException.
Call from the main isolate after initializing PostHog. This does not
require errorTrackingConfig.captureIsolateErrors to be enabled.
Errors are reported as unhandled, with the background stack trace and
this isolate's debug name. Dart supplies the error as a string, not the
original exception object.
Spawn the isolate paused, add the listener, then resume it to avoid missing errors before the listener is registered:
Returns the listener port. Pass it to removePostHogErrorListener to stop forwarding and close the port. The listener is also removed and its port closed automatically when this isolate exits. Existing error listeners and fatal-error behavior are unchanged. Each call installs a separate listener, so call only once per isolate.
Not supported on Flutter web, which has no isolates.
PostHogIsolateExtension.removePostHogErrorListener
Stops forwarding errors and closes the listener's port.
Pass the listener returned by addPostHogErrorListener on this isolate.
Removes both the error listener and its automatic exit-cleanup listener.
Calling this again, including after the isolate exits, is safe.
PostHogLogger
PostHogLogger
Per-level convenience facade for capturing structured logs.
Obtain it via Posthog().logger. Each helper captures a record at its
severity and is equivalent to calling Posthog().captureLog(...) with the
matching level.
Example:
PostHogLogger.debug
Captures a PostHogLogSeverity.debug record.
PostHogLogger.error
Captures a PostHogLogSeverity.error record.
PostHogLogger.fatal
Captures a PostHogLogSeverity.fatal record.
PostHogLogger.info
Captures a PostHogLogSeverity.info record.
PostHogLogger.trace
Captures a PostHogLogSeverity.trace record.
PostHogLogger.warn
Captures a PostHogLogSeverity.warn record.
PostHogMaskWidget
PostHogMaskWidget
Masks a widget subtree in PostHog session replay snapshots.
Wrap sensitive UI with PostHogMaskWidget to hide that area in captured
screenshots, regardless of the global session replay masking settings.
PostHogUnmaskWidget overrides this mask in either nesting order, except
for sensitive text inputs. See that widget's documentation for geometry
limits when revealing part of an enclosing mask.
Flutter web: the canvas is masked by posthog-js rather than by this
plugin, so the first PostHogMaskWidget or PostHogUnmaskWidget to mount
turns canvas masking on —
which restarts an in-flight recording once, because masking also excludes
the Flutter semantics DOM tree via blockSelector, and posthog-js only
reads that when recording starts. Canvas recording itself must be enabled
separately — either with captureCanvas: { recordCanvas: true } as shown
below, or with the canvas capture toggle in your project's session replay
settings. Frames captured before that first mount are recorded unmasked;
to cover the window between posthog.init and Flutter booting, declare
session_recording: { captureCanvas: { recordCanvas: true }, canvasCapture: { maskRegionsFn: () => null } }
in your posthog.init call — until this plugin takes over, those frames are
skipped instead of recorded. Your app must be wrapped in PostHogWidget,
and every mask/unmask widget must sit inside it — otherwise canvas frames
are skipped instead of recorded unmasked, until the mask widget is moved
inside PostHogWidget or removed. iOS and Android need no setup either
way.
PostHogMaskWidget()
Creates a mask around child for session replay.
PostHogMaskWidget.child
The widget subtree to mask in session replay snapshots.
PostHogPlatformView
PostHogPlatformView
Session replay policy marker for an embedded platform view.
Wrap a platform view (e.g. WebViewWidget, GoogleMap) to override the
global PostHogSessionReplayConfig.maskAllPlatformViews setting for that
specific view.
The privacy policy applies to every platform view in the wrapped
subtree, not just the nearest one. Wrapping a container that embeds several
platform views in privacy: capture reveals all of them. A nested
PostHogPlatformView overrides the inherited policy for its own subtree.
This widget has no runtime state — it is a pure marker. The compositor reads privacy from the element tree during each capture frame.
PostHogPlatformView()
Creates a session replay policy marker around child.
PostHogPlatformView.child
The platform view subtree this policy applies to.
PostHogPlatformView.privacy
How the platform views in child are handled in session replay.
Defaults to PostHogPlatformViewPrivacy.mask.
PostHogUnmaskWidget
PostHogUnmaskWidget
Reveals a widget subtree in session replay despite global text/image masking.
Keep maskAllTexts / maskAllImages enabled and reveal only known-safe UI:
Only wrap content known to be safe. This overrides global masking and
PostHogMaskWidget in either nesting order, but sensitive text inputs always
remain masked. Masks on overlapping sibling widgets are not removed.
For an enclosing mask, only the visible rectangular unmask region is excluded. If its transform relative to that mask is not axis-aligned, or a non-rectangular/custom clip prevents a safe exclusion, the enclosing mask is retained. Web masks use conservative bounds and can cover the edges of an unmasked region. Native platform views and captured native screens are unaffected.
On Flutter web, mounting either this widget or PostHogMaskWidget enables
canvas masking and restarts an in-flight recording once to protect the
semantics DOM too. Canvas recording must be enabled separately. Frames
captured before the first mount are not protected by this opt-in. Declare
session_recording: { canvasCapture: { maskRegionsFn: () => null } } in
posthog.init to skip those frames until Flutter installs its mask provider.
Keep both kinds of wrapper inside PostHogWidget on all platforms. On web,
a mounted wrapper outside the tracked tree causes frames to be skipped once
masking is enabled, until it is moved inside or removed.
PostHogUnmaskWidget()
Creates an exception to global text/image masking around child.
PostHogUnmaskWidget.child
The known-safe widget subtree to reveal in session replay.
PostHogWidget
PostHogWidget
Wraps a Flutter app to enable mobile session replay screenshots.
Place PostHogWidget above your app content when PostHogConfig.sessionReplay
is enabled. The widget captures snapshots from child and sends them to the
native SDK while session recording is active.
PostHogWidget()
Creates a session replay root widget around child.
PostHogWidget.child
The widget subtree to include in session replay snapshots.
PosthogObserver
PosthogObserver
A Flutter NavigatorObserver that automatically captures $screen events.
Add this observer to MaterialApp.navigatorObservers or a router such as
go_router to capture screen views when named routes are pushed, popped, or
replaced.
PosthogObserver()
Creates a PostHog route observer.
The nameExtractor reads a screen name from route settings. It defaults
to defaultNameExtractor, which returns RouteSettings.name.
The routeFilter determines which routes are eligible for tracking. It
defaults to defaultPostHogRouteFilter, which tracks PageRoutes.
Screen events are only sent while the app is in the foreground.
Types
BeforeSendCallback
Callback to intercept and modify events before they are sent to PostHog.
The event argument contains the event name and user-provided properties
that are about to be captured. Return a possibly modified event to send it,
or return null to drop it.
Callbacks can be synchronous or asynchronous (returning
FutureOr<PostHogEvent?>).
BeforeSendLogCallback
Callback to intercept and modify log records before they are sent to PostHog.
The record argument contains the body, level, and user-provided
attributes that are about to be captured. Return a possibly modified record
to send it, or return null to drop it.
Callbacks can be synchronous or asynchronous (returning
FutureOr<PostHogLogRecord?>).
PostHogBootstrapConfig
Pre-seeded identity and feature-flag state applied on the very first SDK launch, before any network request completes.
Assign an instance to PostHogConfig.bootstrap before calling
Posthog().setup(config). The values are forwarded to the native iOS/Android
SDKs, which own all bootstrap behavior:
- Bootstrapped identity seeds the very first session only. It is applied only
when no identity is persisted for that scope, and never overwrites an
existing user. An anonymous bootstrap (isIdentifiedId
false) seeds the anonymous id; an identified bootstrap (isIdentifiedIdtrue) seeds the distinct id and marks the user identified (merging an existing anonymous user viaidentify(), or preserving a different identified user with a warning) — it never becomes the device id. - Only enabled bootstrapped flags are served (a
trueor a non-empty variant string;falseor empty values are dropped). They are served until the first/flagsresponse, which then takes over, and they are dropped onreset().
Flutter web: not applied. Configure bootstrap in your
posthog.init({...}) call instead.
PostHogBootstrapConfig()
Creates a bootstrap configuration.
Pass only the dimensions you want to seed; leave the rest null.
PostHogBootstrapConfig.distinctId
The distinct id to seed on first launch.
When isIdentifiedId is false (the default) this becomes the anonymous
id — the $distinct_id on pre-identify events. When true it is treated
as an already-identified user's distinct id.
PostHogBootstrapConfig.featureFlagPayloads
JSON payloads paired with featureFlags, keyed by flag key. Each value is
the already-decoded payload (map, list, string, number, null, ...).
PostHogBootstrapConfig.featureFlags
Feature flag values served until the first /flags response arrives,
keyed by flag key. Each value is a bool for boolean flags or a String
for multivariate flags. Only enabled values are served: false or an
empty string is dropped.
PostHogBootstrapConfig.isIdentifiedId
Whether distinctId represents an already-identified user.
Defaults to false. Set to true when the host application resolved the
user's identity outside the SDK (for example from a backend session token).
PostHogBootstrapConfig.toMap
Converts this configuration to a platform-channel map.
Only the dimensions that were set are included; isIdentifiedId is always sent so the native SDK doesn't have to infer it.
PostHogCompression
Controls how the SDK compresses request bodies before sending them to the PostHog API.
Values
gzip: Gzip request bodies.none: Send request bodies uncompressed.
PostHogConfig
Configuration used to initialize the PostHog Flutter SDK.
Create an instance with your project token, customize any options, and pass
it to Posthog().setup(config).
PostHogConfig()
Creates a configuration for projectToken.
The projectToken is trimmed before it is stored.
The optional onFeatureFlags callback is invoked when feature flags finish
loading.
The optional beforeSend callbacks are copied into beforeSend and run in
order before Dart-captured events are sent.
PostHogConfig.apiKey
Deprecated alias for projectToken.
PostHogConfig.beforeSend
Callbacks to intercept and modify events before they are sent to PostHog.
Callbacks are invoked in order for events captured via Dart APIs:
Posthog().capture()- custom eventsPosthog().screen()- screen events (event name will be$screen)Posthog().captureException()- exception events (event name will be$exception)
Each callback receives the event (possibly modified by previous callbacks).
Return a possibly modified event to continue, or return null to drop it.
Example (single callback):
Example (multiple callbacks):
Example (async callback):
Limitations:
- These callbacks do NOT intercept native-initiated events such as:
- Session replay events (
$snapshot) whenconfig.sessionReplayis enabled - Application lifecycle events (
Application Opened, etc.) whenconfig.captureApplicationLifecycleEventsis enabled - Feature flag events (
$feature_flag_called) whenconfig.sendFeatureFlagEventis enabled - Identity events (
$set) whenidentifyis called - Survey events (
survey shown, etc.) whenconfig.surveysis enabled
- Session replay events (
- Only user-provided properties are available; system properties (like
$device_type,$session_id) are added by the native SDK at a later stage.
Note:
- Callbacks can be synchronous or asynchronous (via
FutureOr<PostHogEvent?>) - If a callback throws, the event is dropped and later callbacks are not called.
- If any callback returns
null, the event is dropped and subsequent callbacks are not called. - On every platform except Windows and Linux, PostHog calls made after a
capture (including
reset(),identify()and getters) wait until its callbacks finish, so the event keeps the user and consent it was captured under. A callback that runs longer than 10 seconds stops holding them back; its event is still sent when it finishes, with the user, super properties, groups and consent current by then. Calls made from inside a callback do not wait, but a callback that waits on a PostHog call made elsewhere stalls until that limit.
PostHogConfig.bootstrap
Pre-seeded identity and feature-flag state applied on the very first SDK launch, before any network request completes.
Set this before calling Posthog().setup(config) so events captured during
cold start carry a caller-controlled $distinct_id and feature-flag reads
return caller-provided values before the first /flags response. Mirrors
the bootstrap option in posthog-js.
Forwarded to the native iOS/Android SDKs, and on Windows/Linux to the
pure-Dart implementation, which apply all precedence rules (never
overwrite persisted identity, overlay loaded flags over bootstrapped ones,
drop the bootstrap on reset()). Defaults to null (no bootstrap).
Flutter web: not applied. The web SDK hooks onto an already-initialized
posthog-js instance, so configure bootstrap in your posthog.init({...})
call instead.
PostHogConfig.captureApplicationLifecycleEvents
Whether the SDK captures application lifecycle events automatically.
Captured events include app opened, backgrounded, installed, and updated
events where supported by the platform. Defaults to true.
PostHogConfig.capturePushNotificationOpened
Whether to automatically capture $push_notification_opened when a user
taps a PostHog-delivered notification.
Every tap on a remote notification is captured on both platforms,
whether it cold-launched the app or the app was already running.
Locally-scheduled notifications are ignored. On Android a tap is
recognised by the google.message_id extra Firebase puts on the intent,
so push delivered outside FCM is not seen. Call
Posthog.capturePushNotificationOpened for the opens this misses.
Flutter web, Windows and Linux: not supported. Defaults to true.
On iOS this requires your app to set UNUserNotificationCenter.current().delegate.
Without one, iOS reports the tap to nobody and no open can be captured.
Setting this to false does not prevent the iOS cold-start prewarm, which runs before
Dart does — opt that out with the com.posthog.posthog.CAPTURE_PUSH_NOTIFICATION_OPENED
key in Info.plist.
PostHogConfig.capturePushNotificationSubscriptions
Whether to automatically register this device's push token or Firebase Installation ID (FID) with PostHog.
On iOS the native SDK swizzles the app delegate's remote-notification
registration callback; on Android it fetches the FCM token at startup when
firebase-messaging is on the classpath, or the FID when the app's manifest
enables firebase_messaging_installation_id_enabled. The host app must
still register with Firebase in FID mode. Either way the host app is still
responsible for requesting notification permission and calling
registerForRemoteNotifications() (iOS) — this only observes the result.
The startup fetch does not see later token refreshes; wire those to Posthog.registerPushNotificationToken yourself.
Flutter web, Windows and Linux: not supported. Defaults to true.
PostHogConfig.compression
Controls how request bodies are compressed before being sent to PostHog.
Set this to PostHogCompression.none when something between the app and PostHog, e.g. a managed network or work profile, alters the gzip body.
Flutter web: not applied. The web SDK hooks onto an already-initialized
posthog-js instance, so set disable_compression: true in your
posthog.init({...}) call instead to match PostHogCompression.none.
Defaults to PostHogCompression.gzip.
PostHogConfig.dataMode
Network connection types that can be used to send data on Apple platforms.
Defaults to PostHogDataMode.any.
PostHogConfig.debug
Whether the SDK emits verbose debug logs.
Defaults to false.
PostHogConfig.enableWindowsAndLinux
Whether the SDK is enabled on Windows and Linux.
Windows and Linux support is experimental. Defaults to true.
Set to false before Posthog.setup to disable the SDK on these
platforms. Other platforms are unaffected. Close the SDK before
changing this setting and calling setup again.
PostHogConfig.errorTrackingConfig
Configuration for error tracking and exception capture.
PostHogConfig.evaluationContexts
Evaluation contexts sent with every /flags request, so only flags
tagged with at least one of these contexts are evaluated.
Defaults to null, which sends no contexts and evaluates every flag.
Flags without evaluation contexts are always evaluated. Use this to keep
flags meant for other apps or environments out of this app's requests.
Flutter web: not applied. posthog-js is initialized by your app, so
set evaluation_contexts in your posthog.init({...}) call instead.
Example:
PostHogConfig.featureFlagRequestMaxRetries
Maximum number of retries for a /flags request after a network error
or a gateway error (HTTP 502 or 504).
The SDK waits 300ms before the first retry and doubles the wait for each later one. A refused connection is not retried.
Defaults to 1. Set to 0 to disable retries; negative values are
treated as 0.
Flutter web: not applied. posthog-js is initialized by your app, so
set feature_flag_request_max_retries in your posthog.init({...}) call
instead.
Example:
PostHogConfig.flushAt
Number of queued events that triggers an automatic flush.
Defaults to 20.
PostHogConfig.flushInterval
Maximum time between automatic flush attempts.
Defaults to 30 seconds.
PostHogConfig.host
The PostHog ingestion host.
Defaults to https://us.i.posthog.com. The setter trims surrounding
whitespace and falls back to the default host when assigned a blank value.
PostHogConfig.logsConfig
Configuration for the logs subsystem (Posthog().captureLog() and the
Posthog().logger facade).
PostHogConfig.maxBatchSize
Maximum number of events sent in a single batch.
Defaults to 50.
PostHogConfig.maxQueueSize
Maximum number of events stored in the local queue.
When the queue is full, the oldest events may be dropped by the native SDK.
Defaults to 1000.
PostHogConfig.onFeatureFlags
Callback to be invoked when feature flags are loaded.
Use Posthog.getFeatureFlag or Posthog.isFeatureEnabled within this callback to access the loaded flag values.
PostHogConfig.optOut
Whether the SDK starts with data collection disabled.
Defaults to false. Use Posthog().optOut() and Posthog().optIn() to
change this setting at runtime.
PostHogConfig.personProfiles
Controls whether captured events create or update person profiles.
Defaults to PostHogPersonProfiles.identifiedOnly.
PostHogConfig.preloadFeatureFlags
Whether feature flags are loaded when the SDK starts.
Defaults to true, which means every SDK start issues a /flags request.
Set it to false if you evaluate flags lazily (via
Posthog().reloadFeatureFlags()) and want to avoid that request.
Note that Posthog().identify(), Posthog().group() and the
set*PropertiesForFlags helpers reload feature flags as well, so turning
preloading off only removes the request made at startup.
Flutter web: not applied. The web SDK hooks onto an already-initialized
posthog-js instance, so set
advanced_disable_feature_flags_on_first_load
in your posthog.init({...}) call instead.
PostHogConfig.projectToken
Your PostHog project token.
You can find it at: https://us.posthog.com/settings/project-details#variables
This field was formerly named apiKey.
PostHogConfig.pushIdentityProvider
Mints a signed identity-verification token for push subscription requests.
Only needed when your PostHog project requires identity verification for
push. The native SDK calls this with the current distinctId and appId
and attaches the returned token to the subscription request; return null
to send without one.
The token is minted by your backend (HS256, with sub = distinctId,
app_id, and aud = posthog:push_identity), never in the app.
The native SDKs cache the result per (distinctId, appId) and give this
callback 10 seconds before falling back to an unauthenticated request, so
a slow or throwing implementation degrades rather than blocking delivery.
Requires programmatic setup on both platforms. Under auto-init
(com.posthog.posthog.AUTO_INIT, Info.plist on iOS, AndroidManifest
<meta-data> on Android) the native SDK is already set up before Dart
runs and a later Posthog.setup is a no-op, so the provider is never
installed. Set com.posthog.posthog.AUTO_INIT to false and call
Posthog.setup.
Flutter web, Windows and Linux: not supported. Defaults to null.
PostHogConfig.rageClickConfig
Configuration for rage-click autocapture on iOS and Mac Catalyst.
Rage-click autocapture is not currently supported on other platforms.
PostHogConfig.sendFeatureFlagEvent
Whether calls that evaluate feature flags capture $feature_flag_called.
Defaults to true.
PostHogConfig.sendFeatureFlagEvents
Deprecated alias for sendFeatureFlagEvent.
PostHogConfig.sessionReplay
Whether mobile session replay is enabled for Android and iOS.
Requires Record user sessions to be enabled in PostHog project settings.
Defaults to false.
PostHogConfig.sessionReplayConfig
Configuration for mobile session replay.
sessionReplay must be enabled for these options to take effect.
PostHogConfig.surveys
Enable Surveys
Notes:
- After calling
Posthog().close(), surveys will not be rendered until the SDK is re-initialized and the next navigation event occurs. - You must install
PosthogObserverin your app for surveys to display. - For Flutter web, this setting will be ignored. Surveys on web use the JavaScript Web SDK instead.
- Surveys are not supported on Windows and Linux, where this setting is ignored.
Defaults to true.
PostHogConfig.toMap
Converts this configuration to a platform-channel map.
Returns the values consumed by the Android, Apple, and web implementations.
PostHogDataMode
Controls which network connection types can be used for sending data.
This setting is currently applied only on Apple platforms.
Values
wifi: Send data only on Wi-Fi connections.cellular: Send data on any available connection, same as any.any: Send data on any available connection.
PostHogErrorTrackingConfig
Configuration for PostHog error tracking and exception capture.
PostHogErrorTrackingConfig()
Creates an error tracking configuration with all autocapture disabled.
PostHogErrorTrackingConfig.captureFlutterErrors
Enable automatic capture of Flutter framework errors.
Controls whether FlutterError.onError errors are captured.
Default: false
PostHogErrorTrackingConfig.captureIsolateErrors
Enable automatic capture of isolate errors.
Only captures errors from the isolate where Posthog().setup() runs,
normally the main isolate. Errors from spawned background isolates are
not captured automatically. To capture them, call
isolate.addPostHogErrorListener() from the main isolate before resuming
an isolate spawned paused.
Note:
- Flutter web: Not supported
Default: false
PostHogErrorTrackingConfig.captureNativeCrashes
Enable automatic capture of native C/C++ (NDK) crashes on Android.
Requires Android 12 (API 31) or later. A native crash kills the process
immediately, so the crash is captured on the next app launch from the
records the OS kept, as an $exception event with raw native stack
frames. Exception autocapture must also be enabled in the project's
error tracking settings.
For symbolicated stack traces, upload the app's .so debug symbols with
the PostHog Gradle plugin.
See: https://posthog.com/docs/error-tracking/upload-mappings/android
Because the event is sent from the next launch, properties like
$app_version reflect the app at capture time, not at crash time.
Note:
- Apple platforms: Not applicable (native crash capture is part of captureNativeExceptions)
- Flutter web: Not supported
- Windows and Linux: Not supported
Default: false
PostHogErrorTrackingConfig.captureNativeExceptions
Enable automatic capture of exceptions in the native SDKs (Android and Apple platforms).
Controls whether native exceptions are captured.
Apple (iOS, macOS, tvOS):
Native error tracking on Apple platforms is currently experimental
Captures Mach exceptions (e.g., EXC_BAD_ACCESS), POSIX signals
(e.g., SIGSEGV, SIGABRT), and uncaught NSExceptions.
Crashes are persisted to disk and sent as $exception events with
level "fatal" on the next app launch.
Not available on watchOS or visionOS due to platform limitations.
For symbolicated stack traces, add a build phase script to your Xcode project to upload debug symbols. See: https://posthog.com/docs/error-tracking/upload-source-maps/ios
Android:
Captures Java/Kotlin exceptions. For native C/C++ (NDK) crashes, also enable captureNativeCrashes.
Stacktrace demangling for minified builds is supported by installing the PostHog Gradle plugin to upload ProGuard/R8 mappings. See: https://posthog.com/docs/error-tracking/upload-mappings/android
Windows and Linux: not supported.
Default: false
PostHogErrorTrackingConfig.capturePlatformDispatcherErrors
Enable automatic capture of Dart runtime errors.
Controls whether PlatformDispatcher.onError errors are captured.
Note:
- Flutter web: Not supported
Default: false
PostHogErrorTrackingConfig.captureSilentFlutterErrors
Enable capturing of silent Flutter errors.
Controls whether Flutter errors marked as silent
(FlutterErrorDetails.silent = true) are captured.
Default: false
PostHogErrorTrackingConfig.exceptionSteps
Configuration for exception steps (breadcrumb-style context records
attached to every captured $exception as $exception_steps).
Record steps with Posthog().addExceptionStep().
PostHogErrorTrackingConfig.inAppByDefault
Configures whether stack trace frames are considered in-app by default when the origin cannot be determined or no explicit includes/excludes match.
- If true: Frames are inApp unless explicitly excluded (allowlist approach)
- If false: Frames are external unless explicitly included (denylist approach)
Default behavior when true:
- Local files (no package prefix) are inApp
- dart and flutter packages are excluded
- All other packages are inApp unless in inAppExcludes
Note:
- Flutter web: Not supported
- Android: Not supported
PostHogErrorTrackingConfig.inAppExcludes
List of package names to exclude from in-app frames for exception tracking.
Use bare Dart package names without the package: URI prefix.
Example:
All exception stack trace frames from these packages will be considered external.
Note: inAppIncludes takes precedence over this setting. Common packages to exclude:
- Third-party analytics packages
- External utility libraries
- Packages you don't control
Note:
- Flutter web: Not supported
- Android: Not supported
PostHogErrorTrackingConfig.inAppIncludes
List of package names to be considered in-app frames for exception tracking.
Use bare Dart package names without the package: URI prefix.
Example:
All exception stack trace frames from these packages will be considered in-app.
This option takes precedence over inAppExcludes. For Flutter/Dart, this typically includes:
- Your app's main package (e.g., "your_app")
- Any internal packages you own (e.g., "your_company_utils")
Note:
- Flutter web: Not supported
PostHogErrorTrackingConfig.toMap
Converts this error tracking configuration to a platform-channel map.
Returns values consumed by the Android, Apple, and Dart exception capture implementations.
PostHogEvent
Represents an event that can be modified or dropped before it is sent.
This class is used in before-send callbacks to allow modification of events before they are sent to PostHog.
PostHogEvent()
Creates an event passed to a before-send callback.
The event is the event name to capture.
The optional properties are event properties that can be amended before
capture.
The optional userProperties are person properties to set with $set.
The optional userPropertiesSetOnce are person properties to set with
$set_once.
PostHogEvent.event
The name of the event (e.g., 'button_clicked', '$screen', '$exception')
PostHogEvent.properties
User-provided properties for this event.
Note: System properties (like $device_type, $session_id, etc.) are added by the native SDK at a later stage and are not available in this map.
PostHogEvent.userProperties
User properties to set on the user profile ($set).
These properties will be merged with any existing user properties.
PostHogEvent.userPropertiesSetOnce
User properties to set only once on the user profile ($set_once).
These properties will only be set if they don't already exist on the user profile.
PostHogExceptionStepsConfig
Configuration for exception steps.
Exception steps are breadcrumb-style context records recorded over time via
Posthog().addExceptionStep(). The SDK keeps a rolling, byte-bounded buffer
of these steps and attaches a snapshot to every captured $exception event
as $exception_steps, giving the error tracking UI a timeline of recent
activity leading up to each error.
The buffer is owned by the embedded native SDK (iOS/Android), so steps also
survive native fatal crashes and attach to the crash $exception reported
on the next launch.
Flutter web: the buffer lives in posthog-js. Steps are forwarded to it,
but they only attach to exceptions captured by posthog-js itself, not to
exceptions captured via Posthog().captureException() on web.
Windows and Linux: the buffer is kept in memory and attaches to every
$exception captured by the app. There are no native crash reports to
attach it to.
PostHogExceptionStepsConfig()
Creates an exception-steps configuration with native defaults.
PostHogExceptionStepsConfig.enabled
Whether recording and attaching exception steps is enabled.
When disabled, Posthog().addExceptionStep() is a no-op and nothing is
attached. Defaults to true.
PostHogExceptionStepsConfig.maxBytes
Total UTF-8 byte budget for the rolling step buffer.
When adding a step would exceed the budget, the oldest steps are evicted
until the total fits. A single step larger than the budget is rejected
outright. Defaults to 32768 (32 KiB).
PostHogExceptionStepsConfig.toMap
Converts this configuration to a platform-channel map.
PostHogFeatureFlagResult
Represents the result of a feature flag evaluation.
Contains the flag key, whether it's enabled, the variant (for multivariate flags), and any associated payload.
PostHogFeatureFlagResult()
Creates a feature flag evaluation result.
The key is the feature flag key that was evaluated.
The enabled value is the boolean result for boolean flags. For
multivariate flags, it is true when the flag evaluates to a variant and
false when it does not match.
The optional variant is the variant key for multivariate flags.
The optional payload is the JSON payload configured for the matched flag
or variant.
PostHogFeatureFlagResult.enabled
Whether the flag is enabled.
For boolean flags, this is the flag value. For multivariate flags, this is true when the flag evaluates to any variant.
PostHogFeatureFlagResult.fromMap
Creates a PostHogFeatureFlagResult from a native SDK response map.
The result should be a map containing key, enabled, variant, and
payload entries. Falls back to fallbackKey if the map does not include
a key.
Returns null if result is null or is not a Map.
PostHogFeatureFlagResult.key
The feature flag key.
PostHogFeatureFlagResult.payload
The JSON payload associated with the flag, if any.
PostHogFeatureFlagResult.variant
The variant key for multivariate flags, or null for boolean flags.
PostHogLogRecord
Represents a log record that can be modified or dropped before it is sent.
This class is passed to the before-send callbacks registered via PostHogLogsConfig.beforeSend to allow modification of log records before they are forwarded to the native SDK.
PostHogLogRecord()
Creates a log record passed to a before-send callback.
The body is the log message.
The level is the severity, defaulting to PostHogLogSeverity.info.
The optional attributes are per-record attributes that can be amended
before capture.
PostHogLogRecord.attributes
User-provided attributes for this record.
Note: Auto-captured context (distinct id, session id, screen name, app state, active feature flags) is added by the native SDK at a later stage and is not available in this map.
PostHogLogRecord.body
The log message body.
PostHogLogRecord.level
The severity level of the record.
PostHogLogSeverity
Severity level for a structured log record captured via
Posthog().captureLog() or the Posthog().logger facade.
The levels map to OpenTelemetry severity numbers (trace=1, debug=5,
info=9, warn=13, error=17, fatal=21). The mapping is performed by
the native SDKs; the Flutter layer forwards the level by name (lowercase),
which both the Android and Apple SDKs parse case-insensitively.
Values
trace: Finest-grained diagnostic detail. High-volume; usually only enabled while diagnosing a problem.debug: Diagnostic detail useful during development.info: Default level for regular runtime events.warn: Something unexpected that is not yet an error.error: A failure that should be looked at.fatal: A critical failure.
PostHogLogsConfig
Configuration for the logs subsystem.
Assign values before calling Posthog().setup(config). The identity and
tuning fields are forwarded to the native iOS/Android logs configuration;
beforeSend runs in Dart before a record is forwarded to the native SDK.
Every field that is null (or, for resourceAttributes, empty) is left at
the native SDK's default — it is not sent over the channel.
Flutter web: this configuration is not applied on web. The web SDK
hooks onto an already-initialized posthog-js instance, so configure logs in
your posthog.init({...}) call instead. Only beforeSend runs on web (in
Dart).
Windows and Linux: logs are not supported. Only beforeSend runs (in Dart); the records it keeps are then dropped.
PostHogLogsConfig()
Creates a logs configuration with native defaults.
PostHogLogsConfig.beforeSend
Callbacks to intercept and modify log records before they are forwarded to the native SDK.
Callbacks are invoked in order for records captured via
Posthog().captureLog() and the Posthog().logger facade. Each callback
receives the record (possibly modified by previous callbacks). Return a
possibly modified record to continue, or return null to drop it.
Blanking the body also drops the record.
Example:
Note:
- Runs in Dart on all platforms — it is intentionally not forwarded to the
native SDKs' own
beforeSend. Dart callbacks cannot cross the platform channel, and running it here gives identical behavior everywhere (including web). This mirrors the event PostHogConfig.beforeSend. - Callbacks can be synchronous or asynchronous (via
FutureOr<PostHogLogRecord?>). - A callback that throws is logged, and the record is dropped.
- The W3C trace fields (
traceId,spanId,traceFlags) are not part of PostHogLogRecord and are not visible here. They pass straight through to the native SDK, so they cannot be redacted or used to drop a record. Keep anything sensitive out of those fields; put it inbodyor PostHogLogRecord.attributes, which a callback can scrub or drop.
PostHogLogsConfig.environment
Sets the OTLP deployment.environment resource attribute (e.g.
production, staging). When null, the native SDK's default is used
(no environment).
PostHogLogsConfig.flushAt
Queue depth that triggers an immediate flush. When null, the native
default is used (20 on iOS/Android).
PostHogLogsConfig.flushInterval
Periodic auto-flush interval. When null, the native default is used
(30s on iOS/Android).
PostHogLogsConfig.maxBatchSize
Maximum number of records sent per POST. When null, the native default
is used (50 on iOS/Android).
PostHogLogsConfig.maxBufferSize
Maximum number of buffered records before the oldest are dropped (FIFO).
When null, the native default is used (1000 on iOS/Android).
PostHogLogsConfig.rateCapMaxLogs
Maximum number of logs accepted per rate-cap window before excess logs are
dropped. When null, the native default is used (500 on iOS/Android). A
non-positive value disables the cap natively.
PostHogLogsConfig.rateCapWindow
Length of the rate-cap window. When null, the native default is used
(10s on iOS/Android).
PostHogLogsConfig.resourceAttributes
Extra OTLP resource attributes merged into every payload.
SDK-managed identity keys (service.*, telemetry.sdk.*) take precedence
and cannot be overridden.
PostHogLogsConfig.serviceName
Sets the OTLP service.name resource attribute.
When null, the native SDK's default is used (the app bundle id on Apple
platforms, the app namespace on Android).
PostHogLogsConfig.serviceVersion
Sets the OTLP service.version resource attribute.
When null, the native SDK's default is used (the app version where the
platform provides one).
PostHogLogsConfig.toMap
Converts the identity and tuning options to a platform-channel map.
Only fields the user set are included, so unset fields keep the native default. beforeSend is intentionally omitted: it runs in Dart and never crosses the platform channel.
PostHogPersonProfiles
Controls whether events create or update PostHog person profiles.
Values
never: Never create person profiles from captured events.always: Create or update person profiles for all captured events.identifiedOnly: Create or update person profiles only after the user has been identified.
PostHogPlatformViewPrivacy
Controls how a platform view is handled in session replay.
Values
mask: Mask the view with a black rectangle (default).capture: Reveal the view content in session replay.
PostHogRageClickConfig
Configuration for rage-click autocapture on iOS and Mac Catalyst.
Assign an instance to PostHogConfig.rageClickConfig before calling
Posthog().setup(config). Other platforms ignore this configuration.
PostHogRageClickConfig()
Creates a rage-click configuration using the native defaults.
PostHogRageClickConfig.enabled
Whether rapid repeated taps are captured as $rageclick events.
Defaults to true.
PostHogRageClickConfig.minimumTapCount
Number of consecutive taps required to capture a rage click.
Defaults to 3.
PostHogRageClickConfig.thresholdPoints
Maximum Manhattan distance, in logical points, between consecutive taps.
Defaults to 30.
PostHogRageClickConfig.timeoutInterval
Maximum time between consecutive taps in the same sequence.
Defaults to one second.
PostHogRageClickConfig.toMap
Converts this rage-click configuration to a platform-channel map.
PostHogRouteFilter
Filters routes before PosthogObserver captures screen views.
Return true to allow tracking for route and false to ignore it. By
default, only PageRoutes are tracked.
PostHogScreenshotColorMode
Pixel format for Android native-screen captures in session replay.
Values
argb8888: Preserve alpha and eight-bit color channels before compression.rgb565: Use half the bitmap memory with reduced color precision and no alpha.
PostHogSessionReplayConfig
Configuration for mobile session replay capture and masking.
Assign an instance to PostHogConfig.sessionReplayConfig before calling
Posthog().setup(config).
PostHogSessionReplayConfig()
Creates a session replay configuration with default masking enabled.
PostHogSessionReplayConfig.captureNativeScreens
Capture native screens that cover the Flutter UI (full-screen paywalls, presented view controllers, native activities) via the native replay SDK, so they appear in replay instead of a frozen Flutter frame. When enabled and a detected screen cannot be captured, a single black placeholder frame is sent instead; if that also fails, replay keeps showing the last Flutter frame. With this flag off there is no placeholder — nothing about replay changes.
Only full-screen, same-process screens are detected. Not captured: partial-height sheets (e.g. Apple Pay, share sheet), other-process content, Android dialogs/Custom Tabs, and iOS covers without an opaque background — replay keeps showing the covered Flutter UI for those.
Opt-in: enabling this starts a lightweight occlusion detector. When false (the default), the covered Flutter tree keeps recording, as before.
Captured native frames honor your maskAllTexts / maskAllImages settings — with the defaults (both true) all native text and images are masked; setting either false reveals it on native screens too.
Applies only to native screens presented over the whole app. For native views embedded in the Flutter layout, see maskAllPlatformViews.
Can be changed at runtime after setup — turning it off before presenting a sensitive native screen guarantees that screen is not captured.
Default: false. Requires native SDK support for on-demand capture.
PostHogSessionReplayConfig.captureTouches
Capture touch coordinates in session replay on Android and iOS.
Masking screenshots does not hide touches on a known keypad layout. Set this before Posthog.setup. Runtime changes are not supported. Disabling touches does not stop screenshot capture.
Default: true. Not supported on web or desktop.
PostHogSessionReplayConfig.debouncerDelay
Deprecated setter that forwards assigned values to throttleDelay.
Debouncer delay used to reduce the number of snapshots captured and reduce performance impact. This is used for capturing the view as a screenshot. The lower the number, the more snapshots will be captured but higher the performance impact. Defaults to 1s.
PostHogSessionReplayConfig.maskAllImages
Enable masking of all images.
Default: true. PostHogUnmaskWidget can reveal known-safe Flutter images;
it overrides explicit masks within the same subtree too. Flutter web
requires canvas masking to be enabled as described in maskAllTexts.
Does not mask images drawn by CustomPainter. Enable maskCustomPaint or wrap sensitive custom-painted widgets in PostHogMaskWidget to mask them.
PostHogSessionReplayConfig.maskAllPlatformViews
Mask all platform views (WebView, Maps, etc.) in session replay.
Default: true.
When true, every platform view is covered with a black rectangle in session replay screenshots. Set to false to opt out globally, or wrap individual views with PostHogPlatformView for per-view control.
Setting this false reveals every texture-backed view, including camera
previews (e.g. the camera plugin) — prefer per-view
PostHogPlatformView opt-ins over the global opt-out.
iOS note: among UiKitViews, setting this false only reveals
WKWebView-backed ones; maps, ARKit and other native views stay masked.
See PostHogPlatformViewPrivacy.capture.
Applies only to native views embedded in the Flutter layout. For native screens presented over the whole app, see captureNativeScreens.
PostHogSessionReplayConfig.maskAllTexts
Enable masking of all text and text input fields.
Default: true. Wrap known-safe Flutter content in PostHogUnmaskWidget
to reveal it without disabling masking globally.
Sensitive Flutter inputs stay masked regardless of this flag, explicit
masks, or unmask widgets. This includes obscureText, password, email,
phone, name, address and URL keyboard types, and standard Flutter autofill
hints for identity, contact, address, authentication, and payment data.
Inputs without these signals are not automatically classified as
sensitive. Annotate them appropriately or keep global masking enabled.
PostHogUnmaskWidget overrides global and explicit masks for other content.
Flutter web requires canvas masking to be enabled by mounting a
PostHogMaskWidget or PostHogUnmaskWidget inside PostHogWidget, or by
declaring session_recording.canvasCapture.maskRegionsFn in posthog.init.
Declare it as () => null to skip frames before Flutter installs its mask
provider. Canvas recording must be enabled separately.
Does not mask text drawn by CustomPainter. Enable maskCustomPaint or wrap sensitive custom-painted widgets in PostHogMaskWidget to mask them.
With captureNativeScreens enabled, setting this false also unmasks text on captured native screens, including native input fields (passwords, card numbers) you may not have built.
PostHogSessionReplayConfig.maskCustomPaint
Mask the full bounds of CustomPaint widgets with a painter or foregroundPainter, including their children. Default: false.
This is independent of maskAllTexts and maskAllImages. Canvas contents cannot be inspected for individual text or images, so enabling this also masks custom-painted decorations in Flutter widgets, including TabBar, checkboxes, switches, and progress indicators. Framework scrollbar-only painters are excluded, but their children are still checked for masks. Disable MaterialApp's debugShowCheckedModeBanner when using this option: its full-window CustomPaint otherwise masks the entire screen.
Frames containing a painter whose bounds cannot be determined, such as a zero-sized CustomPaint, are skipped rather than sent with a missing mask.
PostHogSessionReplayConfig.sampleRate
Session replay sample rate between 0 and 1. Local config has precedence over remote config when both are set. If null, sampling is controlled by remote config (when available).
PostHogSessionReplayConfig.screenshotColorMode
Pixel format for Android native-screen captures.
Applies only to screens recorded with captureNativeScreens.
Defaults to PostHogScreenshotColorMode.argb8888.
Set before Posthog().setup(config).
PostHogSessionReplayConfig.screenshotCompressionQuality
Compression quality for Android replay screenshots.
Flutter screenshots use JPEG; native screens recorded with
captureNativeScreens use WebP. Defaults to 30, clamped to 0–100.
Higher values generally retain more detail and produce larger payloads.
Native capture on Android 10 uses lossless WebP at quality 100; other
supported versions use lossy WebP. Does not change resolution.
Set before Posthog().setup(config).
PostHogSessionReplayConfig.screenshotScale
Multiplier for the width and height of Android replay screenshots.
Defaults to null: Flutter screenshots capture at one pixel per logical
pixel and native screens recorded with captureNativeScreens use the
Android SDK default of one pixel per dp. An explicit value multiplies the
logical size of Flutter screenshots and the physical size of native
screens, so 1.0 captures native screens at physical resolution. Values
are clamped to 0.1–1.0; NaN and infinity reset to null. Scaled
dimensions round up to at least one pixel without changing the logical
replay viewport. Masks round outward to cover output pixels; frames with
mask bounds that cannot be mapped safely are skipped.
Set before Posthog().setup(config).
PostHogSessionReplayConfig.textMaskPolicy
Decides, per text node, what to mask — instead of all-or-nothing.
When set, every plain Text, RichText, and non-sensitive text input is
masked according to the PostHogTextMask the policy returns for its
rendered string, and maskAllTexts no longer applies to those nodes.
Ranges are masked at glyph precision, so a policy can hide an amount
while the label next to it stays readable:
widget is whichever widget actually produced the render object being
captured — RichText for Text and RichText alike, EditableText
for text inputs. It is not the outer Text/TextField an app writes:
Text is a thin wrapper over RichText, and there is no reliable way
to recover it across Flutter's internal composition. Reach for its
style, its InlineSpan, or (for inputs) properties like obscureText
and readOnly — not its key, which will be the framework's, not the
app's.
Precedence, highest first: sensitive inputs (obscureText, password,
card, and other sensitive autofill hints) are always fully masked;
PostHogMaskWidget masks and PostHogUnmaskWidget reveals its subtree
without consulting the policy; then the policy decides; maskAllTexts
only applies to text nodes when no policy is set.
The policy runs on the UI thread for every captured text node; keep it fast. It applies to the Flutter widget tree only — text on captured native screens still follows maskAllTexts, and custom-painted text still needs maskCustomPaint. Can be changed at runtime; the next frame uses the new policy.
It fails closed. Where glyph-precise rects can't be trusted to cover everything the decision asked to hide, the whole node is masked instead:
- the policy throws, or its ranges throw while being read;
- a range falls outside the text, or cuts into a grapheme cluster — Flutter lays out no box for the severed half, so it would otherwise stay readable;
- the node's style paints
shadows, which selection boxes don't bound, so a masked glyph could leave a readable copy of itself wherever its shadow lands; - the node is a paragraph containing a
WidgetSpanand the decision yields anything other than exactly one rect — includingPostHogTextMask.none()andPostHogTextMask.only([]). APostHogUnmaskWidgetnested in that paragraph still reveals its own subtree.
Default: null.
PostHogSessionReplayConfig.throttleDelay
Throttling delay used to reduce the number of snapshots captured and reduce performance impact.
This is used for capturing the view as a screenshot. The lower the number, the more snapshots will be captured but higher the performance impact. Defaults to 1s.
PostHogSessionReplayConfig.toMap
Converts this session replay configuration to a platform-channel map.
Returns values consumed by the Android and Apple session replay implementations.
PostHogSessionReplayConfig.verifyScreenshotMaskAlignment
Verify that masks remain aligned while capturing session replay screenshots.
Android only. This applies only to native-screen captures enabled by captureNativeScreens. Normal Flutter widget screenshots are rendered and masked by Flutter and are unaffected.
Enabling this can preserve screenshots during pixel-only redraws, including continuously animated content, but performs additional view hierarchy walks while a screenshot is captured.
Default: false.
PostHogTextMask
What session replay masks inside one text node.
A PostHogTextMaskPolicy returns one of these for every plain Text,
RichText, and non-sensitive text input that a replay frame captures.
Ranges are character offsets into the node's rendered string, exactly as
it was passed to the policy. Build one with the named constructors, or
match on the four subtypes.
PostHogTextMask.all
Mask the whole node.
PostHogTextMask.except
Mask the whole node except ranges.
An empty ranges masks the whole node.
PostHogTextMask.none
Leave the whole node visible.
PostHogTextMask.only
Mask only ranges; the rest of the node stays visible.
An empty ranges masks nothing.
PostHogTextMaskAll
PostHogTextMask.all: the whole node is masked.
PostHogTextMaskAll()
Creates a decision that masks the whole node.
PostHogTextMaskExcept
PostHogTextMask.except: everything but ranges is masked.
PostHogTextMaskExcept()
Creates a decision that masks everything except ranges.
PostHogTextMaskExcept.ranges
The character ranges to leave visible.
PostHogTextMaskNone
PostHogTextMask.none: the whole node stays visible.
PostHogTextMaskNone()
Creates a decision that leaves the whole node visible.
PostHogTextMaskOnly
PostHogTextMask.only: only ranges are masked.
PostHogTextMaskOnly()
Creates a decision that masks only ranges.
PostHogTextMaskOnly.ranges
The character ranges to mask.
PostHogTextMaskPolicies
Ready-made PostHogTextMaskPolicy implementations.
PostHogTextMaskPolicies.digits
Masks every run of digits and leaves the surrounding words visible.
A run may contain grouping punctuation (, . -) and spaces between
its digits, so a formatted amount or card number is one mask:
₦2,450,000.00 and 4111 1111 1111 1111 are each masked in full, and
in Order 2 of 5 only the 2 and the 5 are.
PostHogTextMaskPolicies.redact
Masks every match of pattern and leaves the rest of the node visible.
PostHogTextMaskPolicies.reveal
Masks the whole node except the matches of pattern.
PostHogTextMaskPolicy
Decides what to mask in a text node, given its rendered string and the widget that produced it.
Set one on PostHogSessionReplayConfig.textMaskPolicy. widget is the
RichText or EditableText that actually produced the render object —
not the outer Text/TextField an app writes, which Flutter composes
away — so inspect its style, its InlineSpan, or (for inputs)
properties like obscureText and readOnly to decide by more than the
string. It is called on the UI thread for every captured text node, so
keep it fast and free of side effects. Throwing masks the whole node.
PushIdentityProvider
Mints a signed identity-verification token for a push subscription request.
Called by the native SDK with the current distinctId and appId. Return
null to send the request without an identity token.
ScreenNameExtractor
Extracts a PostHog screen name from Flutter RouteSettings.
Return null to skip tracking the route. The settings argument is the
route settings from the route being pushed, popped to, or replaced.
defaultNameExtractor
Returns RouteSettings.name as the screen name for settings.
Returns null when the route settings do not define a name.
defaultPostHogRouteFilter
Returns whether route should be tracked by the default route filter.
The default implementation tracks only PageRoute instances.





