Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
75547ff
feat!: run beforeSend on the native-built event on iOS, macOS and And…
turnipdabeets Oct 29, 2026
2d72576
fix: import only the PostHogInternal SPI from posthog-ios
turnipdabeets Oct 29, 2026
ce37fcb
fix: drop built events whose beforeSend callbacks never finish
turnipdabeets Oct 29, 2026
7ce3f1f
fix: clear pending built events on setup and close
turnipdabeets Oct 29, 2026
891a46c
fix: keep primitive arrays when sending built events over the channel
turnipdabeets Oct 29, 2026
ab94c35
feat(desktop): give beforeSend the full event and add nothing after it
turnipdabeets Oct 29, 2026
1000f66
style: merge the repeated guards in buildEvent for swiftformat 0.64
turnipdabeets Oct 29, 2026
8444e94
fix(desktop): keep another distinct id's person properties out of the…
turnipdabeets Oct 29, 2026
1e3bc43
Merge feat/v6-desktop-capture-v1 into feat/v6-before-send-parity
turnipdabeets Oct 30, 2026
0fc1715
test: optOut, close and setup wait for an event being sent
turnipdabeets Oct 30, 2026
1c490bf
fix(beforeSend): run the callbacks set when the event was captured
turnipdabeets Oct 30, 2026
07e2c3b
fix(beforeSend): keep capture semantics for events named $screen
turnipdabeets Oct 30, 2026
8e29c9d
Merge feat/v6-desktop-capture-v1 into feat/v6-before-send-parity
turnipdabeets Oct 30, 2026
5bbccf4
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Oct 30, 2026
ad01dbc
fix(desktop): decide person processing before beforeSend
turnipdabeets Oct 30, 2026
d6eb946
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Oct 31, 2026
a1b24e1
docs: fold #682 release notes into the 6.0 docs
turnipdabeets Oct 31, 2026
5277047
fix(desktop): keep another distinct id's person properties from enabl…
turnipdabeets Nov 2, 2026
a873d08
fix(desktop): decide later events' person processing from what the ap…
turnipdabeets Nov 2, 2026
6f49456
docs: say person processing is decided before beforeSend on native
turnipdabeets Nov 2, 2026
587a732
fix: give beforeSend callbacks typed nested values on iOS, macOS and …
turnipdabeets Nov 2, 2026
a79a138
fix(darwin): expire built events on a monotonic clock
turnipdabeets Nov 2, 2026
db94147
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Nov 3, 2026
88047c2
Merge feat/v6-desktop-capture-v1 into feat/v6-before-send-parity
turnipdabeets Nov 3, 2026
b4795d0
docs: say what the one-minute built-event expiry covers now that call…
turnipdabeets Nov 3, 2026
0009853
fix: keep events and user properties through beforeSend (#698)
turnipdabeets Nov 3, 2026
be52cf4
Merge feat/v6-desktop-capture-v1 into feat/v6-before-send-parity
turnipdabeets Nov 3, 2026
c536d7d
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Nov 3, 2026
f529c38
fix(compliance): pass uuid and prepared-event identity through the ad…
turnipdabeets Nov 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .changeset/v6-major-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@
- **Breaking:** remove the `PostHogSessionReplayConfig.debouncerDelay` setter β€” use `throttleDelay`
- **Breaking:** remove `PostHogDataMode.cellular` β€” use `PostHogDataMode.any`
- **Breaking:** make `beforeSend` and `logsConfig.beforeSend` callbacks synchronous β€” load what they need ahead of time instead of using `await`
- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()` or `captureException()` from applying to that event first, and stop dropping that event on Windows and Linux
- Keep a `reset()`, `identify()` or `optOut()` made right after an un-awaited `capture()`, `screen()`, `captureException()`, `captureFeatureView()` or `captureFeatureInteraction()` from applying to that event first, and stop dropping that event on Windows and Linux
- Run a `beforeSend` callback that renames a screen or exception event once, and keep its `userProperties`
- Keep `userProperties` and `userPropertiesSetOnce` that a `beforeSend` callback sets on a screen or exception event on web
- Send an event as its original user when a `beforeSend` callback calls `reset()` or `identify()` on Windows and Linux, instead of dropping it, and on web, instead of sending it as the new user
- **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API
- **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb`
- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26
Expand All @@ -30,6 +33,8 @@
- **Breaking:** apply SDK properties, then registered properties, then event properties on Windows and Linux, so your value wins for that event, and run `beforeSend` after that merge
- **Breaking:** always set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` header on Windows and Linux, ignoring changes made in `beforeSend`
- **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event
- **Breaking:** pass `beforeSend` callbacks the event the native SDK built on iOS, macOS and Android, with its system and registered properties, and make their changes final
- **Breaking:** decide person processing before `beforeSend` runs on iOS, macOS, Android, Windows and Linux β€” a callback that removes `$set` no longer prevents a person profile, and a callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option
- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks
- Add `captureAi` for AI observability events, a no-op that returns `null` on web
- Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`
Expand All @@ -44,5 +49,8 @@
- Run queued event encoding, file work and request compression on a background isolate on Windows and Linux so they no longer drop frames
- Limit AI events waiting to be written on Windows and Linux to about 50 MiB in memory, dropping the oldest first and completing `captureAi` with `null` for them
- Take an event's timestamp before the `beforeSend` callbacks run on Windows and Linux
- Add `PostHogEvent.uuid`, `distinctId` and `timestamp`, set on every platform except web β€” a callback can change the distinct ID and timestamp, and the event keeps its uuid
- Attach `$exception_steps` before `beforeSend` runs on Windows and Linux so callbacks can read or remove them β€” steps recorded while a callback runs, or an event a callback renames to `$exception`, no longer get them
- Add `PosthogFlutterPlugin.addBeforeSend` in Swift and Kotlin to filter or edit events the native SDK captures itself, such as crashes, app lifecycle and `$feature_flag_called` events
- Declare Android `minSdkVersion` 23 to match `posthog-android`
- Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value
60 changes: 60 additions & 0 deletions api/posthog_flutter.api.json
Original file line number Diff line number Diff line change
Expand Up @@ -5671,6 +5671,33 @@
"name": "options",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "Map<String, Object?>?"
},
{
"isDeprecated": false,
"isExperimental": false,
"isNamed": true,
"isRequired": false,
"name": "uuid",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "String?"
},
{
"isDeprecated": false,
"isExperimental": false,
"isNamed": true,
"isRequired": false,
"name": "distinctId",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "String?"
},
{
"isDeprecated": false,
"isExperimental": false,
"isNamed": true,
"isRequired": false,
"name": "timestamp",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "DateTime?"
}
],
"relativePath": "lib/src/posthog_event.dart",
Expand Down Expand Up @@ -5734,6 +5761,39 @@
"name": "options",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "Map<String, Object?>?"
},
{
"entryPoints": [],
"isDeprecated": false,
"isExperimental": false,
"isReadable": true,
"isStatic": false,
"isWriteable": false,
"name": "uuid",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "String?"
},
{
"entryPoints": [],
"isDeprecated": false,
"isExperimental": false,
"isReadable": true,
"isStatic": false,
"isWriteable": true,
"name": "distinctId",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "String?"
},
{
"entryPoints": [],
"isDeprecated": false,
"isExperimental": false,
"isReadable": true,
"isStatic": false,
"isWriteable": true,
"name": "timestamp",
"relativePath": "lib/src/posthog_event.dart",
"typeName": "DateTime?"
}
],
"isDeprecated": false,
Expand Down
13 changes: 12 additions & 1 deletion posthog_flutter/MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ They serialized the internal platform-channel format and have no replacement. `t

### `beforeSend` callbacks are synchronous

`BeforeSendCallback` is now `PostHogEvent? Function(PostHogEvent)`, and `BeforeSendLogCallback` is `PostHogLogRecord? Function(PostHogLogRecord)`. An `async` callback is a compile error. Load what it needs ahead of time and read it synchronously.
`BeforeSendCallback` is now `PostHogEvent? Function(PostHogEvent)`, and `BeforeSendLogCallback` is `PostHogLogRecord? Function(PostHogLogRecord)`. An `async` callback, or one declared to return `FutureOr<PostHogEvent?>`, is a compile error. Load what it needs ahead of time and read it synchronously.

```dart
// Before
Expand Down Expand Up @@ -258,6 +258,16 @@ On iOS, macOS and Android, a malformed, empty or whitespace-only payload from `g

On iOS and macOS, string values in `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, stay strings instead of being decoded to numbers or booleans.

### `beforeSend` on iOS, macOS and Android

**This is a silent change.** Callbacks now get the event the native SDK built, including its system properties, such as `$device_type` and `$session_id`, and registered properties. Their changes are final. In 5.x they saw only the properties you passed, so a callback that loops over or strips every property now also touches the SDK's. `PostHogEvent` also has `uuid`, `distinctId` and `timestamp`, set on every platform except web.
Comment thread
eli-r-ph marked this conversation as resolved.
Resolved

**Person processing is decided before the callbacks run.** In 5.x, a callback that removed `$set` prevented a person profile. Now the event is still person-processed, and so are later events. Return `null` to drop an event that must not create a profile. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option.

Nested maps are `Map<String, dynamic>`, and a non-empty list of maps is `List<Map<String, dynamic>>`. Any other list is `List<dynamic>`, even a `List<String>` you passed to `capture`, so cast its items instead of the list.

Events the native SDK captures itself don't go through Dart callbacks. Use `PosthogFlutterPlugin.addBeforeSend` in Swift or Kotlin for those.

### Lifecycle events on iOS and macOS

`Application Installed`, `Application Updated` and `Application Opened` no longer include `version` and `build`. Update insights, cohorts and filters that use them to `$app_version` and `$app_build`. Android still sends them.
Expand All @@ -274,6 +284,7 @@ A personal API key (`phx_...`) in `projectToken` now skips `setup()` with one lo

- **Property order:** an event's properties are the SDK's, then registered properties, then the event's own, so your value now wins for that event. `beforeSend` runs after that merge, except that `$lib` and `$lib_version` always come from the `PostHog-Sdk-Info` header.
- **Person processing:** it's sent as the `process_person_profile: false` option only while it's off, instead of a `$process_person_profile` property on every event.
- **`beforeSend` and person processing:** person processing is decided before the callbacks run. A callback that adds `$set` to an anonymous event must also set the `process_person_profile: true` option.
- **Redirects:** only same-origin 307 and 308 redirects are followed. Any other redirect drops the batch.
- **Retries:** a failed batch waits 1 second, doubling up to 30 seconds with Β±25% jitter, instead of retrying within the same flush. `Retry-After` is a floor under that wait, capped at 30 seconds.
- **Writes to disk:** an event is no longer on disk when `capture`, `screen`, `captureException`, `captureFeatureView`, `captureFeatureInteraction`, `identify`, `alias`, `group` or `setPersonProperties` returns, only when the returned future completes. One you didn't await can be lost if the app crashes or calls `exit()` right after. Await the call, or `Posthog().close()`, before `exit()`. Only `close()` also covers events the SDK captures itself, such as `$feature_flag_called`. An `identify` not awaited before `exit()` can lose its `$identify` event for good, because the new ID is already saved. `close()` can now take up to 4 seconds, and a later `setup()` waits for the queue's file work.
Expand Down
Loading
Loading