[turnipdabeets]

Note

Stacked on #877, which is stacked on the 4.0 integration PR #871. Merges into chore/v4-flags-loaded-result.

💡 Motivation and Context

Adds onFeatureFlags(), matching posthog-ios 4.0 onFeatureFlags(_:) and posthog-js onFeatureFlags. Today the only way to hear about flag loads after setup is the single PostHogConfig.onFeatureFlags callback, which a screen or library can't add to or remove.

val subscription = PostHog.onFeatureFlags { loaded ->
    if (loaded.variants["new-checkout"] == "test") {
        // ...
    }
}
// later
subscription.unsubscribe()

• Runs after every feature flags load, with the same PostHogFeatureFlagsLoaded as the config callback (chore!: pass the load result to the feature flags callback #877).
• If flags are already loaded, the new subscriber gets the current flags once right away, so late subscribers don't wait for the next load.
• Available on the instance and as the static PostHog.onFeatureFlags. Listeners stay registered across close() and setup().

For reviewers:

• On Android, listeners run on the main thread, after the getters already return the new values. This follows the on-feature-flags spec ("On SDKs with a main/UI thread, delivery happens on that thread") and matches posthog-ios (feat: add public onFeatureFlags listener with flags, variants and error state posthog-ios#897). The core gets an internal PostHogConfig.featureFlagsListenerExecutor that PostHogAndroid sets to post to the main looper. On the plain JVM, it's unset and listeners run on the remote config thread.
• config.onFeatureFlags and the reloadFeatureFlags callback still run on the remote config thread. iOS splits it the same way: its reload callback stays off main (chore!: mark off-main public callbacks @Sendable for v4 posthog-ios#914). Moving the existing callbacks to main would be its own breaking change, so it's out of scope here.
• PostHogInterface gains an abstract method, which breaks third-party implementations of the interface. That's acceptable in 4.0.
• A load that started before reset() or close() but finishes after is dropped for listeners and not replayed, so listeners never get the previous user's flags after reset(). Each load captures a generation that reset() and close() bump.

💚 How did you test it?

• ./gradlew spotlessCheck apiCheck :posthog:test :posthog-server:test :posthog-android:testDebugUnitTest pass.
• PostHogFeatureFlagsTest covers delivery on each load until unsubscribe(), replay to a late listener, listeners surviving close() and setup(), and no delivery from a reload while disabled. A new test checks that a load finishing after close() reaches no listener and isn't replayed; it fails without the fix. PostHogBootstrapTest covers replay of bootstrapped flags.
• Two tests cover main-thread delivery. PostHogFeatureFlagsTest checks that listeners and late-listener replay run on the listener executor. It also checks that an update queued there is delivered once even when its replay is queued alongside it, and that unsubscribing drops it. PostHogAndroidTest checks that Android posts listeners to the main looper. Each fails without its fix.
• Pixel 9 emulator (API 37) with the sample app against a real project. Before this change, a listener calling setText on an attached view logged CalledFromWrongThreadException, and LiveData.setValue threw (the SDK caught it, so the update was lost). After it, every delivery ran on main, both worked, and the config and reload callbacks stayed on PostHogRemoteConfigThread.

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

Claude Code (Claude Opus 5.5) implemented the listener for flags API parity with iOS 4.0 and Flutter 6, after a cross-SDK review of the flags APIs.

🤖 Generated with Claude Code

[posthog]

PostHog Review · Standard · reviewed b2fbd8b: 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.

[dustinbyrne]

After a failed first real load, onFeatureFlags can emit and replay an empty map even when persisted flags exist and the existing completion returns them. This concerns the failed-load payload, not the accepted cache-only readiness policy.

AI-assisted review.

[dustinbyrne]

Closing the SDK from the bootstrap config callback still lets setup deliver and replay observer flags while disabled. A public-entry regression reproduces this; the earlier failed-load payload fix remains correct. The Android listener's delivery-thread contract also needs reconciliation with current sdk-specs wording.

AI-assisted review.

[dustinbyrne]

The bootstrap-close fix and Android main-thread delivery address the previous findings. One setup-close path remains: a public integration can close the client during installation, after which startup flags are still delivered and replayed while disabled. The new singleton/factory regression reproduces it. Optional threading-doc clarification is inline.

AI-assisted review.

[dustinbyrne]

Approved with an optional note on bootstrap observer ordering when a custom integration starts a reload during installation.

AI-assisted review.