feat!: run beforeSend on the native-built event on iOS, macOS and Android

.changeset/v6-before-send-native-event.md

@@ -0,0 +1,8 @@
+---
+"posthog_flutter": major
+---
+
+- **Breaking:** On iOS, macOS and Android, `beforeSend` callbacks now get the event the native SDK built, with its system and registered properties, and their changes are final, matching Windows and Linux
+- Add `PostHogEvent.uuid`, `distinctId` and `timestamp`, set on every platform but web; a callback can change the distinct ID and timestamp, and the event keeps its uuid
+- On Windows and Linux, attach `$exception_steps` before the `beforeSend` callbacks run, as on iOS and Android, so they 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

.changeset/v6-capture-options-ai.md

@@ -0,0 +1,8 @@
+---
+"posthog_flutter": minor
+---
+
+- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks. The known keys `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On iOS, macOS, Android, Windows and Linux other keys are sent as-is; on web the known keys are sent as their legacy `$` properties and other keys are dropped
+- Add `captureAi` for AI observability events such as `$ai_generation`, sent to PostHog's AI endpoint on iOS, macOS, Android, Windows and Linux, returning the event's UUID, or `null` when the event isn't admitted (dropped by `beforeSend`, oversized, SDK disabled or opted out). On web `captureAi` is a no-op: it sends nothing and returns `null`
+- Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` for the `captureAi` queue and requests. Unset, they keep the SDK defaults. They have no effect on web
+- On Windows and Linux, a `$process_person_profile` property or `process_person_profile` option passed with an event now applies to that event instead of being replaced by the SDK's value

.changeset/v6-desktop-capture-ai.md

@@ -0,0 +1,8 @@
+---
+"posthog_flutter": major
+---
+
+- **Breaking:** on Windows and Linux, an event's properties are now the ones the SDK sets (device and app context, `$lib`, feature flags, `$session_id`, `$is_identified`, the `$sdk_debug_*` keys), then registered properties, then the event's own, as in `posthog-ios` and `posthog-android` 4.0. A registered or event property with the same name as an SDK property now wins, for that event only. The Dart `beforeSend` callbacks run after that merge, so they see and can change every property and option the SDK adds, and the event is sent as they leave it, except `$lib` and `$lib_version`: PostHog always sets them from the SDK's `PostHog-Sdk-Info` header
+- **Breaking:** on Windows and Linux, person processing is sent as the `process_person_profile: false` option only while it is off, instead of a `$process_person_profile` property on every event
+- On Windows and Linux, `captureAi` queues AI events on disk apart from other events. The queue keeps up to `captureAiMaxQueueSize` events (100 by default) and 50 MiB, drops a serialized event over `captureAiMaxEventBytes` (8 MiB plus 64 KiB by default, measured before compression) and is sent like other events: same batching, retries and backoff, compressed with `captureAiCompression`, a request failing after `captureAiTimeout` (60 seconds by default) without progress
+- On Windows and Linux, an event's timestamp is taken before the `beforeSend` callbacks run

.changeset/v6-desktop-capture-v1.md

@@ -2,7 +2,7 @@
 "posthog_flutter": major
 ---
 
-- **Breaking:** on every platform, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer <token>`), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides
+- **Breaking:** on iOS, macOS, Android, Windows and Linux, events now go to capture v1 (`/i/v1/analytics/events`) instead of `/batch/`: iOS and macOS through `posthog-ios` 4.x, Android through `posthog-android` 4.x, and Windows and Linux in the Dart client. If you send events through your own reverse proxy, update it before you upgrade: forward `/i/v1/analytics/events` and `/i/v1/ai/events`, pass `Authorization` (the project token, sent as `Bearer <token>`), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged, and accept request bodies up to 20 MB. PostHog's managed reverse proxy already does this. See the [iOS](https://github.com/PostHog/posthog-ios/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) and [Android](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md#hosts-without-capture-v1) migration guides
 - **Breaking:** on Windows and Linux, a reverse proxy or self-hosted instance must serve the new path: a 404 is retried, the events stay queued, and the SDK prints a warning once, also without `debug`. Events queued before the upgrade are sent through the new endpoint
 - **Breaking:** on Windows and Linux, a redirect drops the batch instead of retrying it (only same-origin 307/308 redirects are followed, while a 404 or 429 is retried), and a `Retry-After` wait is capped at 30 seconds
 - On Windows and Linux, a failed batch, or one whose events the server asks to retry, is no longer resent within the same flush: the queue backs off like the iOS and Android SDKs, waiting 1 second and doubling up to 30 seconds with ±25% jitter, until a batch is delivered. A `Retry-After` is a floor under that wait rather than a replacement

.changeset/v6-flags-loaded-result.md

@@ -0,0 +1,6 @@
+---
+"posthog_flutter": major
+---
+
+- **Breaking:** `PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed. Update callbacks from `() { ... }` to `(loaded) { ... }` (or `(_) { ... }`)
+- **Breaking:** `reloadFeatureFlags()` now returns a `Future<PostHogFeatureFlagsLoaded>` with the reloaded flags

.changeset/v6-posthog-android-4.md

@@ -0,0 +1,5 @@
+---
+"posthog_flutter": major
+---
+
+- **Breaking:** adopt `posthog-android` 4.x

.changeset/v6-posthog-ios-4.md

@@ -0,0 +1,8 @@
+---
+"posthog_flutter": major
+---
+
+- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26
+- **Breaking:** return `null` instead of the raw string for a malformed, empty, or whitespace-only `getFeatureFlagResult()` payload on iOS and macOS
+- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans
+- **Breaking:** stop sending the legacy `version` and `build` properties on `Application Installed`, `Application Updated` and `Application Opened` on iOS and macOS — use `$app_version` and `$app_build`. Android still sends them until `posthog-android` drops them

.github/workflows/sdk-compliance.yml

@@ -14,8 +14,8 @@ on:
 jobs:
   compliance:
     name: PostHog SDK compliance tests
-    uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@27806196fa5c5ac74e9e7500bc46b74db1869f3a # main @ 2026-07-27
+    uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@c90b42dbe2235c89aad3b4dddf74f520a8c6c747 # 1.26.0
     with:
       adapter-dockerfile: "sdk_compliance_adapter/Dockerfile"
       adapter-context: "."
-      test-harness-version: "0.9.0"
+      test-harness-version: "1.26.0"