[turnipdabeets]

💡 Motivation and Context

Stacked on #637. This is the part of v6 that needs the posthog-ios 4.0 and posthog-android 4.0 majors, split out so #637 can pass CI against the 3.x SDKs. Merge this once both are released.

• Raise the posthog-ios range to 4.x (the iOS 15 / macOS 11 minimums are already in chore!: Flutter Major Release v6 #637), and drive onFeatureFlags from the posthog-ios onFeatureFlags listener, since 4.0 removes the didReceiveFeatureFlags notification
• Raise the posthog-android range to [4.0.0,5.0.0) (chore!: adopt posthog-android 4.0 #663). The plugin calls none of the APIs 4.0 removes
• Pass a PostHogFeatureFlagsLoaded (enabled flags, their values, errorsLoading) to PostHogConfig.onFeatureFlags and return it from reloadFeatureFlags() on every platform (chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags #664, closes Add full onFeatureFlags callback with flags, variants, and error state #231). This matches posthog-ios 4.0 (feat: add public onFeatureFlags listener with flags, variants and error state posthog-ios#897, #913), posthog-android 4.0 (chore!: pass the load result to the feature flags callback posthog-android#877) and posthog-js. On web, reloadFeatureFlags() awaits posthog-js reloadFeatureFlagsAsync() (1.438.2+). With older posthog-js it waits for the next onFeatureFlags call, with a timeout that covers posthog-js retries
• One changeset, which covers:
  • adopting both 4.x majors
  • the new onFeatureFlags / reloadFeatureFlags() types
  • the payload decoding changes from chore!: note posthog-ios 4.0 feature flag payload decoding changes #644 (chore!: return nil for malformed feature flag payloads posthog-ios#903)
  • iOS and macOS no longer sending the legacy version/build properties on lifecycle events (chore!: drop legacy version and build from lifecycle events posthog-ios#905). Android keeps sending them for now

💚 How did you test it?

• CI. This will not go green until posthog-ios 4.0 and posthog-android 4.0 are published.
• Locally, with Xcode 26.4.1: built the example app for the iOS simulator and for macOS against posthog-ios 4.0, with the open 4.0 PRs chore!: remove wireframe session replay capture posthog-ios#907 and #909 merged in, pointing Package.swift temporarily at the local checkout with .package(path:). The plugin produced no warnings, including for the @Sendable callback from chore!: mark off-main public callbacks @Sendable for v4 posthog-ios#914. Not tested locally: the CocoaPods build.
• chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags #664: flutter analyze, flutter test, scripts/check-api-dart.sh (snapshot updated), new method-channel, desktop and web handler tests, flutter build web, and Chrome checks of the web reload path.
• Not yet built: Android against posthog-android 4.0.

📝 Checklist

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

🤖 Generated with Claude Code

[github-actions]

posthog-flutter Compliance Report

Date: 2026-10-30 16:31:06 UTC
Duration: 96320ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	122ms
Format Validation.Event Has Uuid	✅	110ms
Format Validation.Event Has Lib Properties	✅	108ms
Format Validation.Distinct Id Is String	✅	107ms
Format Validation.Token Is Present	✅	108ms
Format Validation.Custom Properties Preserved	✅	108ms
Format Validation.Event Has Timestamp	✅	109ms
Retry Behavior.Retries On 503	✅	5315ms
Retry Behavior.Does Not Retry On 400	✅	2111ms
Retry Behavior.Does Not Retry On 401	✅	2110ms
Retry Behavior.Respects Retry After Header	✅	8115ms
Retry Behavior.Implements Backoff	✅	15417ms
Retry Behavior.Retries On 500	✅	5216ms
Retry Behavior.Retries On 502	✅	5216ms
Retry Behavior.Retries On 504	✅	5215ms
Retry Behavior.Max Retries Respected	✅	15429ms
Deduplication.Generates Unique Uuids	✅	115ms
Deduplication.Preserves Uuid On Retry	✅	5209ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10320ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5219ms
Deduplication.No Duplicate Events In Batch	✅	114ms
Deduplication.Different Events Have Different Uuids	✅	110ms
Compression.Sends Gzip When Enabled	✅	110ms
Batch Format.Uses Proper Batch Structure	✅	109ms
Batch Format.Flush With No Events Sends Nothing	✅	105ms
Batch Format.Multiple Events Batched Together	✅	114ms
Error Handling.Does Not Retry On 403	✅	2111ms
Error Handling.Does Not Retry On 413	✅	2111ms
Error Handling.Retries On 408	✅	5217ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	9ms
Request Payload.Flags Request Uses V2 Query Param	✅	5ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	5ms
Request Payload.Flags Request Omits Authorization Header	✅	5ms
Request Payload.Token In Flags Body Matches Init	✅	5ms
Request Payload.Groups Round Trip	✅	5ms
Request Payload.Groups Default To Empty Object	✅	5ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	5ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	5ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	4ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	5ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	107ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	9ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	5ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	108ms

[github-actions]

This PR hasn't seen activity in a week! Should it be merged, closed, or further worked on? If you want to keep it open, post a comment or remove the stale label – otherwise this will be closed in another week.

[eli-r-ph]

Adopting posthog-ios 4.0 moves Flutter's iOS events to capture v1, but the Dart API doesn't expose options or captureAi yet, so Flutter users get v1's stricter rules without its new APIs, and $ai_* events stay on the analytics endpoint. Could Flutter 6 add options (including on PostHogEvent for beforeSend) and captureAi, passing them to native on iOS and mapping them to legacy properties and a plain capture on Android and web? If that's too much for 6.0, I wonder if we should hold on shipping the partial v1 implementation just for Flutter/iOS now? I'm concerned that another breaking-change upgrade after the release to get in parity with the public release docs and features of the other v1 SDKs may be too confusing for end users? I'm also open to just converting all these related SDKs/plugins at once instead so they can all be consistent now? What do you think we should do?

[eli-r-ph]

Adopting posthog-ios 4 moves iOS and macOS events to capture v1, while Android stays on /batch. Can the changeset say so and link the iOS 4.0 migration guide? Proxy users need to forward /i/v1/analytics/events, stop putting their proxy auth in the Authorization header, and know that distinct IDs over 200 bytes are dropped on iOS only.

[eli-r-ph]

Adopting posthog-ios 4.0 moves iOS and macOS events to capture v1 (/i/v1/analytics/events). A reverse proxy must forward the new path and the Authorization header, or events are dropped. Could the changeset say so and link the posthog-ios 4.0 migration guide, as the Windows and Linux changeset does?

[eli-r-ph]

🤔 I think this was all addressed elsewhere but let me know if not - I made managed proxy cfg changes for prod, but SDK migration guides will need to call out new required header allowances, req size caps etc. suitable for capture v1 analytics and AI shaped events as prep work for users on DIY proxies

[turnipdabeets]

Thanks! Flutter 6.0 adopts posthog-ios 4.0 (this PR) and posthog-android 4.0 (#663), and #673 moves Windows and Linux, so every platform moves to capture v1. I've updated the capture v1 changeset in #673 (cdaefeb) to cover all platforms. It lists what a DIY proxy needs: forward /i/v1/analytics/events and /i/v1/ai/events, pass Authorization, the PostHog-* headers, Content-Type, Content-Encoding and User-Agent through unchanged, and accept request bodies up to 20 MB. It also links the native migration guides, which are still in review:

• iOS: Hosts without capture v1 (feat!: remove the /batch fallback from capture V1 posthog-ios#940)
• Android: Hosts without capture v1 (feat!: add captureAi on the capture v1 AI endpoint posthog-android#884)

[turnipdabeets]

@eli-r-ph Thanks, agreed that we shouldn't ship v1 without its APIs. #674 adds them in 6.0: options on capture/screen/identify/setPersonProperties/alias/group/captureException and on PostHogEvent for beforeSend, plus captureAi, both passed to native on iOS, macOS and Android (Android now has native captureAi via posthog-android 4.0 in #663). Now that Windows and Linux send through capture v1 (#673), I'm adding a real /i/v1/ai/events route to the Dart desktop sender for captureAi, rather than a plain-capture fallback. Web is the one gap: posthog-js has no AI capture, so captureAi there sends nothing and returns null. I can make web fall back to a plain capture instead if you think keeping those events is worth sending them through the analytics endpoint. 6.0 ships with #674 and the desktop AI route.