feat: add an onFeatureFlags listener you can unsubscribe

.changeset/v6-on-feature-flags-listener.md

@@ -0,0 +1,5 @@
+---
+"posthog_flutter": minor
+---
+
+- Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`

api/posthog_flutter.api.json

@@ -4526,6 +4526,28 @@
                         "type": "method",
                         "typeParameterNames": []
                     },
+                    {
+                        "entryPoints": [],
+                        "isDeprecated": false,
+                        "isExperimental": false,
+                        "isStatic": false,
+                        "name": "onFeatureFlags",
+                        "parameters": [
+                            {
+                                "isDeprecated": false,
+                                "isExperimental": false,
+                                "isNamed": false,
+                                "isRequired": true,
+                                "name": "callback",
+                                "relativePath": "lib/src/posthog.dart",
+                                "typeName": "void Function(PostHogFeatureFlagsLoaded)"
+                            }
+                        ],
+                        "relativePath": "lib/src/posthog.dart",
+                        "returnTypeName": "PostHogFeatureFlagsSubscription",
+                        "type": "method",
+                        "typeParameterNames": []
+                    },
                     {
                         "entryPoints": [],
                         "isDeprecated": false,
@@ -6110,6 +6132,36 @@
                 ],
                 "typeParameterNames": []
             },
+            {
+                "entryPoints": [
+                    "posthog_flutter.dart"
+                ],
+                "executableDeclarations": [
+                    {
+                        "entryPoints": [],
+                        "isDeprecated": false,
+                        "isExperimental": false,
+                        "isStatic": false,
+                        "name": "unsubscribe",
+                        "parameters": [],
+                        "relativePath": "lib/src/feature_flags_loaded.dart",
+                        "returnTypeName": "void",
+                        "type": "method",
+                        "typeParameterNames": []
+                    }
+                ],
+                "fieldDeclarations": [],
+                "isDeprecated": false,
+                "isExperimental": false,
+                "isRequired": false,
+                "isSealed": false,
+                "name": "PostHogFeatureFlagsSubscription",
+                "relativePath": "lib/src/feature_flags_loaded.dart",
+                "superTypeNames": [
+                    "Object"
+                ],
+                "typeParameterNames": []
+            },
             {
                 "entryPoints": [
                     "posthog_flutter.dart"

posthog_flutter/android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt

@@ -94,6 +94,12 @@ class PosthogFlutterPlugin :
     @Volatile
     private var isHostActivityStopped = false
 
+    // Dart's feature flags lifecycle, sent with setup, reset and close. Each
+    // flags notification carries the one current when it fired, so Dart can
+    // drop loads from before a reset or close.
+    @Volatile
+    private var flagsGeneration = 0
+
     // A count, not a boolean: under multi-resume (Android 10+ split-screen)
     // two non-host activities can be resumed at once, and pausing one must
     // not read as "nothing covers the host" while the other still does.
@@ -274,6 +280,7 @@ class PosthogFlutterPlugin :
             }
 
             "reset" -> {
+                updateFlagsGeneration(call)
                 reset(result)
             }
 
@@ -354,6 +361,7 @@ class PosthogFlutterPlugin :
             }
 
             "close" -> {
+                updateFlagsGeneration(call)
                 close(result)
             }
 
@@ -550,6 +558,7 @@ class PosthogFlutterPlugin :
                 return
             }
 
+            updateFlagsGeneration(call)
             setupPostHog(args)
 
             result.success(null)
@@ -826,7 +835,10 @@ class PosthogFlutterPlugin :
                 onFeatureFlags =
                     PostHogFeatureFlagsCallback { loaded ->
                         Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.")
-                        invokeFlutterMethod("onFeatureFlagsCallback", loaded.toFlutterMap())
+                        invokeFlutterMethod(
+                            "onFeatureFlagsCallback",
+                            loaded.toFlutterMap() + ("generation" to flagsGeneration),
+                        )
                     }
             }
 
@@ -2173,6 +2185,10 @@ class PosthogFlutterPlugin :
         }
     }
 
+    private fun updateFlagsGeneration(call: MethodCall) {
+        call.argument<Int>("flagsGeneration")?.let { flagsGeneration = it }
+    }
+
     private fun close(result: Result) {
         try {
             PostHog.close()

posthog_flutter/darwin/posthog_flutter/Sources/posthog_flutter/PosthogFlutterPlugin.swift

@@ -45,6 +45,24 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
     private var channel: FlutterMethodChannel?
     private var featureFlagsSubscription: PostHogFeatureFlagsSubscription?
 
+    // Dart's feature flags lifecycle, sent with setup, reset and close. Each
+    // flags notification carries the one current when it fired, so Dart can
+    // drop loads from before a reset or close.
+    private let flagsGenerationLock = NSLock()
+    private var flagsGenerationValue = 0
+    private var flagsGeneration: Int {
+        get {
+            flagsGenerationLock.lock()
+            defer { flagsGenerationLock.unlock() }
+            return flagsGenerationValue
+        }
+        set {
+            flagsGenerationLock.lock()
+            flagsGenerationValue = newValue
+            flagsGenerationLock.unlock()
+        }
+    }
+
     // Mint route for pushIdentityProvider, anchored to the engine whose setup()
     // installed the provider. A live owner is never displaced; provider-enabled
     // engines stay candidates so detach promotes the most recent survivor instead
@@ -88,7 +106,15 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
     }
 
     func featureFlagsDidUpdate(_ loaded: PostHogFeatureFlagsLoaded) {
-        invokeFlutterMethod("onFeatureFlagsCallback", arguments: Self.featureFlagsLoadedMap(loaded))
+        var arguments = Self.featureFlagsLoadedMap(loaded)
+        arguments["generation"] = flagsGeneration
+        invokeFlutterMethod("onFeatureFlagsCallback", arguments: arguments)
+    }
+
+    private func updateFlagsGeneration(_ call: FlutterMethodCall) {
+        if let generation = (call.arguments as? [String: Any])?["flagsGeneration"] as? Int {
+            flagsGeneration = generation
+        }
     }
 
     private static func featureFlagsLoadedMap(_ loaded: PostHogFeatureFlagsLoaded) -> [String: Any] {
@@ -466,6 +492,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
     public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
         switch call.method {
         case "setup":
+            updateFlagsGeneration(call)
             setup(call, result: result)
         case "getFeatureFlag":
             getFeatureFlag(call, result: result)
@@ -494,6 +521,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
         case "distinctId":
             distinctId(result)
         case "reset":
+            updateFlagsGeneration(call)
             reset(result)
         case "enable":
             enable(result)
@@ -526,6 +554,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
         case "addExceptionStep":
             addExceptionStep(call, result: result)
         case "close":
+            updateFlagsGeneration(call)
             close(result)
         case "sendMetaEvent":
             sendMetaEvent(call, result: result)

posthog_flutter/lib/posthog_flutter_web.dart

@@ -3,6 +3,7 @@
 // package as the core of your plugin.
 import 'dart:async';
 import 'dart:js_interop';
+import 'dart:js_interop_unsafe';
 
 import 'package:flutter/services.dart';
 import 'package:flutter_web_plugins/flutter_web_plugins.dart';
@@ -12,6 +13,7 @@ import 'package:posthog_flutter/src/utils/channel_serialization.dart';
 import 'package:posthog_flutter/src/utils/property_normalizer.dart';
 
 import 'src/feature_flag_result.dart';
+import 'src/feature_flags_listeners.dart';
 import 'src/feature_flags_loaded.dart';
 import 'src/logs/posthog_log_severity.dart';
 import 'src/posthog_config.dart';
@@ -36,6 +38,11 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
   /// Copied at setup. Event beforeSend runs here, before posthog-js, the same
   /// way [PosthogFlutterIO] runs it before the platform channel.
   List<BeforeSendCallback> _beforeSendCallbacks = [];
+  JSFunction? _featureFlagsUnsubscribe;
+
+  /// Bumped by each setup() and close(), so a posthog-js registration from an
+  /// earlier one stops delivering even when it can't be unsubscribed.
+  int _featureFlagsGeneration = 0;
 
   // posthog-js has no current screen, so the feature events get it from here
   // the way native SDKs stamp it: the last screen beforeSend accepted, under
@@ -135,19 +142,38 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
 
     WebCanvasMaskProvider(config).register();
 
-    if (config.onFeatureFlags != null && ph != null) {
-      final dartCallback = config.onFeatureFlags!;
+    // Skipped for a posthog-js stub without onFeatureFlags.
+    if (ph != null && (ph as JSObject).has('onFeatureFlags')) {
+      final dartCallback = config.onFeatureFlags;
+      // Repeated setup would otherwise deliver each load twice.
+      _featureFlagsUnsubscribe?.callAsFunction();
+      _featureFlagsUnsubscribe = null;
+      final generation = ++_featureFlagsGeneration;
 
       // JS SDK calls with: (flags: string[], variants: Record, context?: {errorsLoading})
       final jsCallback =
           (JSArray jsFlags, JSObject jsFlagVariants, [JSObject? jsContext]) {
-        dartCallback(featureFlagsLoadedFromMap({
+        // The posthog-js loader snippet queues the registration and returns
+        // no unsubscribe, so a later setup() or close() can't remove it.
+        if (generation != _featureFlagsGeneration) return;
+        final loaded = featureFlagsLoadedFromMap({
           'variants': jsFlagVariants.dartify(),
           'errorsLoading': (jsContext?.dartify() as Map?)?['errorsLoading'],
-        }));
+        });
+        // First, so a throwing config callback can't starve listeners and a
+        // reset() or close() it starts clears this load.
+        FeatureFlagsListeners.instance.deliver(loaded);
+        dartCallback?.call(loaded);
       }.toJS;
 
-      ph.onFeatureFlags(jsCallback);
+      // posthog-js replays loaded flags synchronously, and a callback may call
+      // close() or setup() before this returns the unsubscribe.
+      final unsubscribe = ph.onFeatureFlags(jsCallback);
+      if (generation == _featureFlagsGeneration) {
+        _featureFlagsUnsubscribe = unsubscribe;
+      } else {
+        unsubscribe?.callAsFunction();
+      }
     }
   }
 
@@ -378,7 +404,14 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
 
   @override
   Future<void> reset() async {
-    return _call(const MethodCall('reset'));
+    return _order.run(() {
+      // Posthog.reset() cleared this when the app called it, but a load can
+      // still arrive while the reset waits behind an async beforeSend.
+      // posthog-js sends no empty load on reset, so nothing else would replace
+      // that load for listeners added later.
+      FeatureFlagsListeners.instance.clear();
+      return handleWebMethodCall(const MethodCall('reset'));
+    });
   }
 
   @override
@@ -532,6 +565,9 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface {
   @override
   Future<void> close() async {
     _currentScreen = null;
+    _featureFlagsUnsubscribe?.callAsFunction();
+    _featureFlagsUnsubscribe = null;
+    _featureFlagsGeneration++;
     return _call(const MethodCall('close'));
   }
 

posthog_flutter/lib/src/feature_flags_listeners.dart

@@ -0,0 +1,65 @@
+import 'dart:async';
+
+import 'package:meta/meta.dart';
+
+import 'feature_flags_loaded.dart';
+import 'posthog_flutter_platform_interface.dart';
+import 'util/logging.dart';
+
+/// Delivers each feature flags load to the listeners added with
+/// [Posthog.onFeatureFlags].
+@internal
+class FeatureFlagsListeners {
+  FeatureFlagsListeners._();
+
+  static final instance = FeatureFlagsListeners._();
+
+  final _listeners = <Object, OnFeatureFlagsCallback>{};
+  PostHogFeatureFlagsLoaded? _last;
+  int _generation = 0;
+
+  /// Bumped by [clear]. The native SDKs tag each load with the generation
+  /// they last got, so a load sent before a `reset()` or `close()` reached
+  /// them can be told apart.
+  int get generation => _generation;
+
+  PostHogFeatureFlagsSubscription add(OnFeatureFlagsCallback listener) {
+    final token = Object();
+    _listeners[token] = listener;
+    final current = _last;
+    if (current != null) {
+      // Skipped if a newer load already reached the listener.
+      scheduleMicrotask(() {
+        if (_listeners.containsKey(token) && identical(_last, current)) {
+          _notify(listener, current);
+        }
+      });
+    }
+    return PostHogFeatureFlagsSubscription(() => _listeners.remove(token));
+  }
+
+  void deliver(PostHogFeatureFlagsLoaded loaded) {
+    _last = loaded;
+    for (final entry in _listeners.entries.toList()) {
+      // An earlier listener may have unsubscribed this one.
+      if (_listeners.containsKey(entry.key)) _notify(entry.value, loaded);
+    }
+  }
+
+  // A throwing listener must not stop the others from getting the load.
+  void _notify(
+      OnFeatureFlagsCallback listener, PostHogFeatureFlagsLoaded loaded) {
+    try {
+      listener(loaded);
+    } catch (e) {
+      printIfDebug('onFeatureFlags listener threw: $e');
+    }
+  }
+
+  /// Forgets the last load, so new listeners don't get the previous user's
+  /// flags after `reset()` or `close()`.
+  void clear() {
+    _last = null;
+    _generation++;
+  }
+}

posthog_flutter/lib/src/feature_flags_loaded.dart

@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 /// The feature flags passed to [PostHogConfig.onFeatureFlags] and returned by
 /// [Posthog.reloadFeatureFlags].
 ///
@@ -51,3 +53,18 @@ class PostHogFeatureFlagsLoaded {
   String toString() =>
       'PostHogFeatureFlagsLoaded(variants: $variants, errorsLoading: $errorsLoading)';
 }
+
+/// A listener added with [Posthog.onFeatureFlags].
+///
+/// Call [unsubscribe] to stop receiving feature flags updates.
+class PostHogFeatureFlagsSubscription {
+  final void Function() _unsubscribe;
+
+  /// Not part of the public API.
+  @internal
+  PostHogFeatureFlagsSubscription(this._unsubscribe);
+
+  /// Stops the listener from receiving further updates. Calling it again has
+  /// no effect.
+  void unsubscribe() => _unsubscribe();
+}