[turnipdabeets]

💡 Motivation and Context

On iOS, macOS and Android, Dart beforeSend callbacks ran on the raw call input, before the native SDK added its properties. The native properties won afterwards, so a callback couldn't see or remove device, app, session or registered properties, and it had no uuid, timestamp or distinct id. Windows, Linux and the native iOS and Android SDKs already run beforeSend on the final event. This brings Flutter mobile in line with them in 6.0. Changing what the callback receives later would be a breaking change.

Calling the Dart hook from inside native beforeSend doesn't work: native hooks are synchronous and method channels are async, the same problem #255 hit. Instead, the event takes two calls: native builds the event, Dart runs the callbacks, then native sends the result.

Depends on unreleased native APIs. It needs buildEventForWrapper / sendBuiltEventForWrapper from PostHog/posthog-android#904 and PostHog/posthog-ios#991. The native ranges stay 4.0.0 ..< 5.0.0, since both APIs are meant to ship in 4.0.0. Merge this only after both native PRs land.

Changes

• Mobile beforeSend: with callbacks set, capture, captureAi, screen and captureException call buildEvent, run the callbacks on the built event, then call sendBuiltEvent. A dropped event calls discardBuiltEvent, which only frees the plugin's copy. With no callbacks, an event still takes the single existing native call.
• PostHogEvent: new uuid (read-only), distinctId and timestamp fields, set on iOS, macOS and Android. $set and $set_once still arrive as userProperties / userPropertiesSetOnce, as on desktop.
• Native hooks: PosthogFlutterPlugin.addBeforeSend in Swift and Kotlin covers events the native SDK captures itself (crashes, lifecycle, $feature_flag_called, replay, identify). These hooks run after the plugin's $flutter_version hook.
• Unchanged: identify, alias, group and setPersonProperties still don't go through the Dart hook (documented).
• Plugin internals: the plugin holds each built event between the two calls, so native-only state on the event survives. An event whose callbacks haven't finished after a minute is dropped on the next build, so a callback that never completes can't hold it in memory. On Android, native values the channel can't carry (for example a Date registered natively) are sent to Dart as strings.
• Cleanup: the old Dart-side hook path is removed, since it only ran with no callbacks.

💚 How did you test it?

• flutter test: all 1381 tests pass, including new tests for the build → callbacks → send flow, drops, the no-callback single call, field mapping, AI lane and exception timestamp. The event-shape snapshots were updated after reviewing the diff.
• flutter analyze is clean, ktlint and swiftformat pass, and the public API dump is updated.
• New Kotlin test for addBeforeSend ordering.
• Not done: the Swift and Kotlin plugin code hasn't been compiled against the native branches yet, and nothing was run on a device. The native APIs are still in review.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written with Claude Code. The approach (native build → Dart hook → native send, plus a native-side hook) was picked over three alternatives: calling Dart from native beforeSend (ruled out because native hooks are synchronous), having Dart rebuild the properties (they'd drift from native state), and documenting the gap. Ran an automated code review before pushing; fixes from it are in this commit (no-throw handling of unreadable built events, blank distinctId ignored, codec-safe Android values, dead code removed).

[posthog]

PostHog Review · Standard · reviewed 893daf8: 2 Must fix, 2 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[github-actions]

posthog-flutter Compliance Report

Date: 2026-10-29T20:58:51.235643+00:00
Duration: 97185ms

✅ All Tests Passed!

47/47 tests passed

---

Capture Tests

✅ 30/30 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	133ms
Format Validation.Event Has Uuid	✅	117ms
Format Validation.Event Has Lib Properties	✅	113ms
Format Validation.Distinct Id Is String	✅	112ms
Format Validation.Token Is Present	✅	111ms
Format Validation.Custom Properties Preserved	✅	114ms
Format Validation.Event Has Timestamp	✅	112ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	113ms
Retry Behavior.Retries On 503	✅	5326ms
Retry Behavior.Does Not Retry On 400	✅	2115ms
Retry Behavior.Does Not Retry On 401	✅	2114ms
Retry Behavior.Respects Retry After Header	✅	8116ms
Retry Behavior.Implements Backoff	✅	15441ms
Retry Behavior.Retries On 500	✅	5216ms
Retry Behavior.Retries On 502	✅	5221ms
Retry Behavior.Retries On 504	✅	5220ms
Retry Behavior.Max Retries Respected	✅	15439ms
Deduplication.Generates Unique Uuids	✅	120ms
Deduplication.Preserves Uuid On Retry	✅	5220ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10331ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5225ms
Deduplication.No Duplicate Events In Batch	✅	117ms
Deduplication.Different Events Have Different Uuids	✅	113ms
Compression.Sends Gzip When Enabled	✅	112ms
Batch Format.Uses Proper Batch Structure	✅	111ms
Batch Format.Flush With No Events Sends Nothing	✅	107ms
Batch Format.Multiple Events Batched Together	✅	119ms
Error Handling.Does Not Retry On 403	✅	2114ms
Error Handling.Does Not Retry On 413	✅	2113ms
Error Handling.Retries On 408	✅	5218ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	10ms
Request Payload.Flags Request Uses V2 Query Param	✅	7ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	6ms
Request Payload.Flags Request Omits Authorization Header	✅	7ms
Request Payload.Token In Flags Body Matches Init	✅	6ms
Request Payload.Groups Round Trip	✅	7ms
Request Payload.Groups Default To Empty Object	✅	6ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	7ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	7ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	7ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	109ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	13ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	7ms
Retry Behavior.Retries Flags On 502	✅	110ms
Retry Behavior.Retries Flags On 504	✅	111ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	113ms

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[posthog]

PostHog Review · Standard · reviewed 749478a: 1 Must fix.

[posthog]

PostHog Review · Standard · reviewed 980eee4: 1 Should fix.

This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.