From 21be8e68a4af8c15204594db080a1ff57792fa04 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 18:50:32 -0400 Subject: [PATCH 1/2] feat(flags): add defaultValue to isFeatureEnabled --- .changeset/calm-flags-default.md | 5 ++ api/posthog_flutter.api.json | 27 ++++++++ posthog_flutter/lib/posthog_flutter_web.dart | 3 +- posthog_flutter/lib/src/posthog.dart | 19 +++++- .../lib/src/posthog_flutter_desktop.dart | 6 +- .../lib/src/posthog_flutter_io.dart | 10 ++- .../posthog_flutter_platform_interface.dart | 3 +- .../lib/src/posthog_flutter_web_handler.dart | 1 + .../test/posthog_flutter_desktop_test.dart | 62 +++++++++++++++++++ .../test/posthog_flutter_io_test.dart | 55 ++++++++++++++++ ...sthog_flutter_platform_interface_fake.dart | 3 +- .../posthog_flutter_web_handler_test.dart | 41 ++++++++++++ posthog_flutter/test/posthog_test.dart | 7 +++ 13 files changed, 233 insertions(+), 9 deletions(-) create mode 100644 .changeset/calm-flags-default.md diff --git a/.changeset/calm-flags-default.md b/.changeset/calm-flags-default.md new file mode 100644 index 000000000..1061bf2d7 --- /dev/null +++ b/.changeset/calm-flags-default.md @@ -0,0 +1,5 @@ +--- +'posthog_flutter': minor +--- + +Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value diff --git a/api/posthog_flutter.api.json b/api/posthog_flutter.api.json index 87102cdbc..19a730529 100644 --- a/api/posthog_flutter.api.json +++ b/api/posthog_flutter.api.json @@ -787,6 +787,15 @@ "name": "sendFeatureFlagEvent", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "bool?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "defaultValue", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "bool?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -1840,6 +1849,15 @@ "name": "sendFeatureFlagEvent", "relativePath": "lib/src/posthog_flutter_platform_interface.dart", "typeName": "bool?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "defaultValue", + "relativePath": "lib/src/posthog_flutter_platform_interface.dart", + "typeName": "bool?" } ], "relativePath": "lib/src/posthog_flutter_platform_interface.dart", @@ -4507,6 +4525,15 @@ "name": "sendFeatureFlagEvent", "relativePath": "lib/src/posthog.dart", "typeName": "bool?" + }, + { + "isDeprecated": false, + "isExperimental": false, + "isNamed": true, + "isRequired": false, + "name": "defaultValue", + "relativePath": "lib/src/posthog.dart", + "typeName": "bool?" } ], "relativePath": "lib/src/posthog.dart", diff --git a/posthog_flutter/lib/posthog_flutter_web.dart b/posthog_flutter/lib/posthog_flutter_web.dart index 045f88ca3..0d07e63a7 100644 --- a/posthog_flutter/lib/posthog_flutter_web.dart +++ b/posthog_flutter/lib/posthog_flutter_web.dart @@ -413,11 +413,12 @@ class PosthogFlutterWeb extends PosthogFlutterPlatformInterface { @override Future isFeatureEnabled(String key, - {bool? sendFeatureFlagEvent}) async { + {bool? sendFeatureFlagEvent, bool? defaultValue}) async { final result = await _call( MethodCall('isFeatureEnabled', { 'key': key, if (sendFeatureFlagEvent != null) 'sendEvent': sendFeatureFlagEvent, + if (defaultValue != null) 'defaultValue': defaultValue, }), ); return result as bool? ?? false; diff --git a/posthog_flutter/lib/src/posthog.dart b/posthog_flutter/lib/src/posthog.dart index 7465914b4..9427444f3 100644 --- a/posthog_flutter/lib/src/posthog.dart +++ b/posthog_flutter/lib/src/posthog.dart @@ -471,7 +471,14 @@ class Posthog { /// [PostHogConfig.sendFeatureFlagEvent]. Pass `false` to skip the event for /// this call, or `true` to capture it even when the config turns it off. /// - /// Returns `false` when the flag is disabled, missing, or not a boolean flag. + /// [defaultValue] is what this call returns when the flag has no value. + /// Defaults to `null`, which returns `false`. A flag has no value when flags + /// have not loaded yet, the flags request failed, or no flag has this key. A + /// flag that has a value always wins, including `false` and variants, and + /// `$feature_flag_called` never reports [defaultValue] as the flag's value. + /// + /// Returns `false` when the flag is disabled, and `true` when it is enabled + /// or set to a variant. /// /// **Example:** /// ```dart @@ -479,10 +486,16 @@ class Posthog { /// sendFeatureFlagEvent: false)) { /// // show the new checkout without recording a flag exposure /// } + /// + /// // Keep the feature on until the flag says otherwise. + /// final showCheckout = + /// await Posthog().isFeatureEnabled('new-checkout', defaultValue: true); /// ``` - Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent}) => + Future isFeatureEnabled(String key, + {bool? sendFeatureFlagEvent, bool? defaultValue}) => _posthog.isFeatureEnabled(key, - sendFeatureFlagEvent: sendFeatureFlagEvent); + sendFeatureFlagEvent: sendFeatureFlagEvent, + defaultValue: defaultValue); /// Reloads feature flags for the current user. /// diff --git a/posthog_flutter/lib/src/posthog_flutter_desktop.dart b/posthog_flutter/lib/src/posthog_flutter_desktop.dart index cf883e54a..511c78b22 100644 --- a/posthog_flutter/lib/src/posthog_flutter_desktop.dart +++ b/posthog_flutter/lib/src/posthog_flutter_desktop.dart @@ -442,12 +442,14 @@ class PosthogFlutterDesktop extends PosthogFlutterPlatformInterface { _guard('unregister', (client) => client.unregister(key)); @override - Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent}) => + Future isFeatureEnabled(String key, + {bool? sendFeatureFlagEvent, bool? defaultValue}) => _guardWith( 'isFeatureEnabled', - false, + defaultValue ?? false, (client) => client.isFeatureEnabled(key, sendEvent: sendFeatureFlagEvent) ?? + defaultValue ?? false); @override diff --git a/posthog_flutter/lib/src/posthog_flutter_io.dart b/posthog_flutter/lib/src/posthog_flutter_io.dart index 759050404..4f6386c68 100644 --- a/posthog_flutter/lib/src/posthog_flutter_io.dart +++ b/posthog_flutter/lib/src/posthog_flutter_io.dart @@ -589,7 +589,15 @@ class PosthogFlutterIO extends PosthogFlutterPlatformInterface { @override Future isFeatureEnabled(String key, - {bool? sendFeatureFlagEvent}) async { + {bool? sendFeatureFlagEvent, bool? defaultValue}) async { + if (defaultValue != null) { + // Native isFeatureEnabled returns a plain Bool, which can't tell a missing + // flag from a disabled one. Both call the same native flag read. + final result = await getFeatureFlagResult( + key: key, sendFeatureFlagEvent: sendFeatureFlagEvent); + return result?.enabled ?? defaultValue; + } + if (!isSupportedPlatform()) { return false; } diff --git a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart index a775d5f76..e90928342 100644 --- a/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart +++ b/posthog_flutter/lib/src/posthog_flutter_platform_interface.dart @@ -169,7 +169,8 @@ abstract class PosthogFlutterPlatformInterface extends PlatformInterface { throw UnimplementedError('unregister() has not been implemented.'); } - Future isFeatureEnabled(String key, {bool? sendFeatureFlagEvent}) { + Future isFeatureEnabled(String key, + {bool? sendFeatureFlagEvent, bool? defaultValue}) { throw UnimplementedError('isFeatureEnabled() has not been implemented.'); } diff --git a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart index d35dd08da..0f4b97cbc 100644 --- a/posthog_flutter/lib/src/posthog_flutter_web_handler.dart +++ b/posthog_flutter/lib/src/posthog_flutter_web_handler.dart @@ -320,6 +320,7 @@ Future handleWebMethodCall(MethodCall call) async { final isFeatureEnabled = posthog ?.isFeatureEnabled(stringToJSAny(key), _flagOptions(args)) ?.dartify() as bool? ?? + args['defaultValue'] as bool? ?? false; return isFeatureEnabled; case 'group': diff --git a/posthog_flutter/test/posthog_flutter_desktop_test.dart b/posthog_flutter/test/posthog_flutter_desktop_test.dart index 36517dd8d..fd5b35b47 100644 --- a/posthog_flutter/test/posthog_flutter_desktop_test.dart +++ b/posthog_flutter/test/posthog_flutter_desktop_test.dart @@ -109,6 +109,11 @@ void main() { expect(await platform.isFeatureEnabled('flag'), isFalse); }); + test('isFeatureEnabled returns the default', () async { + expect( + await platform.isFeatureEnabled('flag', defaultValue: true), isTrue); + }); + test('isOptOut reports opted out', () async { expect(await platform.isOptOut(), isTrue); }); @@ -1808,6 +1813,63 @@ void main() { expect(view['distinct_id'], distinctId); }); + test('isFeatureEnabled defaultValue only applies to flags with no value', + () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json({ + 'flags': { + ..._variantFlagResponse()['flags']! as Map, + 'off-flag': {'key': 'off-flag', 'enabled': false}, + }, + }); + final flagsLoaded = Completer(); + final config = configFor(server) + ..onFeatureFlags = () { + if (!flagsLoaded.isCompleted) flagsLoaded.complete(); + }; + final platform = await setUpPlatform(config); + await flagsLoaded.future; + + expect(await platform.isFeatureEnabled('missing', defaultValue: true), + isTrue); + expect(await platform.isFeatureEnabled('missing', defaultValue: false), + isFalse); + expect(await platform.isFeatureEnabled('off-flag', defaultValue: true), + isFalse); + expect( + await platform.isFeatureEnabled('variant-flag', defaultValue: false), + isTrue); + }); + + test(r'$feature_flag_called does not report the defaultValue', () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); + final flagsLoaded = Completer(); + final config = configFor(server) + ..onFeatureFlags = () { + if (!flagsLoaded.isCompleted) flagsLoaded.complete(); + }; + final platform = await setUpPlatform(config); + await flagsLoaded.future; + + await platform.isFeatureEnabled('missing', defaultValue: true); + + final called = await server.waitForEvent(r'$feature_flag_called'); + expect(_propertiesOf(called)[r'$feature_flag_response'], isNull); + }); + + test( + 'isFeatureEnabled returns the defaultValue after a failed flags request', + () async { + final server = await LocalPostHogServer.start(); + server.respond = (_) => const PostHogResponse(500); + final platform = await setUpPlatform(configFor(server)); + await platform.reloadFeatureFlags(); + + expect(await platform.isFeatureEnabled('missing', defaultValue: true), + isTrue); + }); + test(r'sendFeatureFlagEvent false skips $feature_flag_called', () async { final server = await LocalPostHogServer.start(); server.respond = (_) => PostHogResponse.json(_variantFlagResponse()); diff --git a/posthog_flutter/test/posthog_flutter_io_test.dart b/posthog_flutter/test/posthog_flutter_io_test.dart index 6bbf65eb2..c64567016 100644 --- a/posthog_flutter/test/posthog_flutter_io_test.dart +++ b/posthog_flutter/test/posthog_flutter_io_test.dart @@ -156,6 +156,61 @@ isolate_dso_base: 7000000000 } }); + group('PosthogFlutterIO isFeatureEnabled defaultValue', () { + void respondToFlagResult(Object? Function() respond) { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger + .setMockMethodCallHandler(channel, (call) async { + log.add(call); + return respond(); + }); + } + + for (final (name, native, defaultValue, expected) + in <(String, Map?, bool, bool)>[ + ('missing flag returns default true', null, true, true), + ('missing flag returns default false', null, false, false), + ( + 'false flag beats default true', + {'key': 'flag', 'enabled': false, 'variant': null}, + true, + false, + ), + ( + 'variant beats default false', + {'key': 'flag', 'enabled': true, 'variant': 'test'}, + false, + true, + ), + ]) { + test(name, () async { + respondToFlagResult(() => native); + + expect( + await posthogFlutterIO.isFeatureEnabled('flag', + defaultValue: defaultValue), + expected); + }); + } + + test('forwards sendFeatureFlagEvent and never sends the default', () async { + respondToFlagResult(() => null); + + await posthogFlutterIO.isFeatureEnabled('flag', + sendFeatureFlagEvent: false, defaultValue: true); + + expect(log.single.method, 'getFeatureFlagResult'); + expect(log.single.arguments, {'key': 'flag', 'sendEvent': false}); + }); + + test('native failure returns the default', () async { + respondToFlagResult(() => throw PlatformException(code: 'failed')); + + expect( + await posthogFlutterIO.isFeatureEnabled('flag', defaultValue: true), + isTrue); + }); + }); + group('PosthogFlutterIO getAllFeatureFlags', () { test('decodes the native results', () async { TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger diff --git a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart index b71a0bfe8..c629e5bd1 100644 --- a/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart +++ b/posthog_flutter/test/posthog_flutter_platform_interface_fake.dart @@ -284,11 +284,12 @@ class PosthogFlutterPlatformFake extends PosthogFlutterPlatformInterface { @override Future isFeatureEnabled(String key, - {bool? sendFeatureFlagEvent}) async { + {bool? sendFeatureFlagEvent, bool? defaultValue}) async { flagReadCalls.add({ 'method': 'isFeatureEnabled', 'key': key, 'sendFeatureFlagEvent': sendFeatureFlagEvent, + if (defaultValue != null) 'defaultValue': defaultValue, }); return featureFlagValues[key] == true; } diff --git a/posthog_flutter/test/posthog_flutter_web_handler_test.dart b/posthog_flutter/test/posthog_flutter_web_handler_test.dart index 35ab74c05..22ddb1daf 100644 --- a/posthog_flutter/test/posthog_flutter_web_handler_test.dart +++ b/posthog_flutter/test/posthog_flutter_web_handler_test.dart @@ -274,6 +274,47 @@ void main() { } }); + group('PosthogFlutterWeb isFeatureEnabled defaultValue', () { + late Object? receivedOptions; + + void installFlagValue(JSAny? value) { + final fake = JSObject(); + fake.setProperty( + 'isFeatureEnabled'.toJS, + ((JSString key, JSAny? options) { + receivedOptions = options.dartify(); + return value; + }).toJS, + ); + globalContext.setProperty('posthog'.toJS, fake); + } + + for (final (name, value, defaultValue, expected) + in <(String, JSAny?, bool, bool)>[ + ('missing flag returns default true', null, true, true), + ('missing flag returns default false', null, false, false), + ('false flag beats default true', false.toJS, true, false), + ('variant beats default false', true.toJS, false, true), + ]) { + test(name, () async { + installFlagValue(value); + + expect( + await PosthogFlutterWeb() + .isFeatureEnabled('flag', defaultValue: defaultValue), + expected); + }); + } + + test('does not pass the default to posthog-js', () async { + installFlagValue(null); + + await PosthogFlutterWeb().isFeatureEnabled('flag', defaultValue: true); + + expect(receivedOptions, {}); + }); + }); + group('PosthogFlutterWeb getAllFeatureFlags', () { test('decodes the posthog-js results', () async { final fake = JSObject(); diff --git a/posthog_flutter/test/posthog_test.dart b/posthog_flutter/test/posthog_test.dart index a3d9f7adf..f9e418ee0 100644 --- a/posthog_flutter/test/posthog_test.dart +++ b/posthog_flutter/test/posthog_test.dart @@ -449,12 +449,19 @@ void main() { await Posthog().getFeatureFlag('b', sendFeatureFlagEvent: false); await Posthog().isFeatureEnabled('c'); await Posthog().isFeatureEnabled('d', sendFeatureFlagEvent: true); + await Posthog().isFeatureEnabled('e', defaultValue: true); expect(fake.flagReadCalls, [ {'method': 'getFeatureFlag', 'key': 'a', 'sendFeatureFlagEvent': null}, {'method': 'getFeatureFlag', 'key': 'b', 'sendFeatureFlagEvent': false}, {'method': 'isFeatureEnabled', 'key': 'c', 'sendFeatureFlagEvent': null}, {'method': 'isFeatureEnabled', 'key': 'd', 'sendFeatureFlagEvent': true}, + { + 'method': 'isFeatureEnabled', + 'key': 'e', + 'sendFeatureFlagEvent': null, + 'defaultValue': true, + }, ]); }); From ace59139576b596245b06201129a75ff1bc9217d Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 22:13:48 -0400 Subject: [PATCH 2/2] docs: fold #694 release notes into the 6.0 docs --- .changeset/calm-flags-default.md | 5 ----- .changeset/v6-major-release.md | 1 + 2 files changed, 1 insertion(+), 5 deletions(-) delete mode 100644 .changeset/calm-flags-default.md diff --git a/.changeset/calm-flags-default.md b/.changeset/calm-flags-default.md deleted file mode 100644 index 1061bf2d7..000000000 --- a/.changeset/calm-flags-default.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'posthog_flutter': minor ---- - -Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value diff --git a/.changeset/v6-major-release.md b/.changeset/v6-major-release.md index 9d30fb0ea..8c785d3bf 100644 --- a/.changeset/v6-major-release.md +++ b/.changeset/v6-major-release.md @@ -15,3 +15,4 @@ - **Breaking:** remove `toMap()` from the config classes and `PostHogFeatureFlagResult.fromMap()` from the public API - **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb` - Declare Android `minSdkVersion` 23 to match `posthog-android` +- Add a `defaultValue` option to `isFeatureEnabled()`, returned when the flag has no value