[turnipdabeets]

💡 Motivation and Context

Stacked on #670. Ships with PostHog/posthog-android#918, which removes the field natively. #918 is merged into posthog-android's chore/v4-remove-deprecated but not yet feat/v4-capture-v1. This PR still builds against feat/v4-capture-v1, because the plugin only stops reading the field (built on Nov 3 through #699, which contains this PR). Makes Posthog().onFeatureFlags(callback) the only flag-load listener, matching iOS 4, Android 4 and posthog-js.

Breaking: removes PostHogConfig.onFeatureFlags. Migration: call Posthog().onFeatureFlags((loaded) { ... }) before setup().

• The Android plugin now subscribes to PostHog.onFeatureFlags on engine attach and unsubscribes on detach, as the iOS/macOS plugin does.
• That listener also fires after a manual reload, so the Dart-side Android-only reload delivery is gone. It also fixes the "not called after reload" Android caveat.

💚 How did you test it?

• flutter analyze, flutter test (1318 passed, 1 skipped), scripts/check-api-dart.sh.
• flutter test --platform chrome on the two web files: the 3 app version tests fail, as reported on the base; the rest pass.

Ran through the Flutter example with local posthog-android and posthog-ios against a local mock server (Android emulator API 37, iOS 26.4 simulator). Temporary overrides lived in a throwaway worktree.

Question	Android	iOS
Listener registered before setup() gets the first load (cold start)	{known-on, checkout}, errorsLoading=false	same
Bootstrap values reach it, before the network load	{boot-flag, boot-variant}, then the /flags values	same
/flags 500 on relaunch	last known flags, errorsLoading=true	same
Late listener gets current flags once	once, then once per reload	same

🧪 How to test locally (for agents and reviewers)

CI's build-android and build-apple jobs can't pass until posthog-ios and posthog-android 4.0 are released, because no 4.x version resolves yet. To test now, build against the native feat/v4-capture-v1 branches. Don't commit these overrides.

Android: check out feat/v4-capture-v1 of posthog-android, then:

sed -i '' -E 's/^coreVersion=.*/coreVersion=7.99.0/; s/^androidVersion=.*/androidVersion=4.99.0/' gradle.properties
./gradlew :posthog:publishToMavenLocal :posthog-android:publishToMavenLocal -x signMavenPublication

Add mavenLocal() as the first repository in example/android/build.gradle.kts. Use a new version for each republish, because Gradle can reuse a stale one.

iOS/macOS: check out feat/v4-capture-v1 of posthog-ios and point posthog_flutter/darwin/posthog_flutter/Package.swift at it:

.package(name: "posthog-ios", path: "/absolute/path/to/posthog-ios"),

Build: from example/, with Swift Package Manager enabled (flutter config --enable-swift-package-manager), run flutter build apk --debug and flutter build ios --simulator --debug.

Local server: set config.host to http://127.0.0.1:<port>.

• Android: add android:usesCleartextTraffic="true" to <application> and run adb reverse tcp:<port> tcp:<port>.
• iOS: set NSAppTransportSecurity > NSAllowsArbitraryLoads in Runner/Info.plist.
• Server: use HTTP/1.1, and return {"hasFeatureFlags": true} from /array/<token>/config. Otherwise Android skips /flags and reports empty flags.

Run tests on a device with flutter test integration_test/<file>.dart -d <device>.

What to check on this PR: the same listener scenarios as #670, using its test and server, with listeners replacing config.onFeatureFlags.

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

🤖 Generated with Claude Code

[github-actions]

posthog-flutter Compliance Report

Date: 2026-11-03T18:47:01.670156+00:00
Duration: 97125ms

✅ All Tests Passed!

47/47 tests passed

---

Capture Tests

✅ 30/30 tests passed

View Details

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

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[marandaneto]

Automated advisory code review.