Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
00643ec
chore!: adopt posthog-ios 4.0
turnipdabeets Oct 7, 2026
ddbe08e
docs(changeset): note posthog-ios 4.0 drops lifecycle version and build
turnipdabeets Oct 7, 2026
69a3ef8
chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags …
turnipdabeets Oct 23, 2026
d358430
chore!: adopt posthog-android 4.0 (#663)
turnipdabeets Oct 29, 2026
7eebbca
docs(changeset): fold the posthog-android 4.0 and flags-loaded entrie…
turnipdabeets Oct 29, 2026
4220eb0
feat: add an onFeatureFlags listener you can unsubscribe
turnipdabeets Oct 25, 2026
0677b43
fix: isolate failing flag listeners, skip web registration without on…
turnipdabeets Oct 25, 2026
b130bcf
fix: deliver flag loads to onFeatureFlags listeners before the config…
turnipdabeets Oct 27, 2026
7aaa9b8
fix(web): stop flag registrations left by close() or the posthog-js l…
turnipdabeets Oct 28, 2026
1431994
fix: drop native flag loads sent before a reset or close reached native
turnipdabeets Oct 28, 2026
b71f8d6
fix: start receiving native flag loads when the first listener is added
turnipdabeets Oct 28, 2026
4d81d9e
fix: deliver Android reloadFeatureFlags results to onFeatureFlags lis…
turnipdabeets Oct 28, 2026
284cdec
chore: stop passing RRStyle to replay screenshot frames (#684)
turnipdabeets Oct 29, 2026
d04ec3a
Merge chore/v6-posthog-ios-4 into chore/v6-adopt-posthog-ios-4
turnipdabeets Oct 30, 2026
53e1279
Merge chore/v6-adopt-posthog-ios-4 into feat/v6-on-feature-flags-list…
turnipdabeets Oct 30, 2026
1538fa6
fix(web): clear replayed flags when a queued reset reaches posthog-js
turnipdabeets Oct 30, 2026
df6371d
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Oct 31, 2026
08a1e41
docs: fold #670 release notes into the 6.0 docs
turnipdabeets Oct 31, 2026
e8e6bac
fix: don't throw when SDK calls run before the Flutter binding exists
turnipdabeets Nov 2, 2026
28bc2f0
Merge feat/v6-desktop-capture-v1 into feat/v6-on-feature-flags-listener
turnipdabeets Nov 2, 2026
6f86b4a
Merge feat/v6-desktop-capture-v1 into feat/v6-on-feature-flags-listener
turnipdabeets Nov 2, 2026
1c24b72
Merge remote-tracking branch 'origin/feat/v6-desktop-capture-v1' into…
turnipdabeets Nov 3, 2026
241eb5b
Merge feat/v6-desktop-capture-v1 into feat/v6-on-feature-flags-listener
turnipdabeets Nov 3, 2026
2cd9136
fix: stop delivering a flags load that a listener's reset() or close(…
turnipdabeets Nov 3, 2026
e9a2ab0
feat!: remove PostHogConfig.onFeatureFlags in favor of the listener (…
turnipdabeets Nov 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .changeset/v6-major-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
- **Breaking:** rename `enable()` and `disable()` to `optIn()` and `optOut()` on `PosthogFlutterPlatformInterface`, `PosthogFlutterIO` and `PosthogFlutterWeb`
- **Breaking:** adopt `posthog-ios` 4.x, which requires Xcode 26
- **Breaking:** adopt `posthog-android` 4.x
- **Breaking:** pass a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed to `PostHogConfig.onFeatureFlags` — update callbacks from `() { ... }` to `(loaded) { ... }` or `(_) { ... }`
- **Breaking:** remove `PostHogConfig.onFeatureFlags` — call `Posthog().onFeatureFlags((loaded) { ... })` before `setup()` instead, which also covers the first load
- **Breaking:** return the reloaded flags from `reloadFeatureFlags()` as a `Future<PostHogFeatureFlagsLoaded>`
- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only `getFeatureFlagResult()` payload on iOS, macOS and Android
- **Breaking:** keep string payloads passed to `PostHogBootstrapConfig.featureFlagPayloads`, such as `"123"`, as strings on iOS and macOS instead of decoding them to numbers or booleans
Expand All @@ -32,6 +32,8 @@
- **Breaking:** send person processing as the `process_person_profile: false` option on Windows and Linux, only while it's off, instead of a `$process_person_profile` property on every event
- Add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` for `beforeSend` callbacks
- Add `captureAi` for AI observability events, a no-op that returns `null` on web
- Add `Posthog().onFeatureFlags()` to get notified after every feature flags load, returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`
- Skip SDK calls with a warning instead of throwing when they run before the Flutter binding is initialized on iOS, macOS and Android
- Add `PostHogConfig.captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes`
- Apply a `$process_person_profile` property or `process_person_profile` option passed with an event to that event on Windows and Linux
- Skip `setup()` with one log line when `projectToken` is a personal API key (`phx_`), so the key is never sent
Expand Down
72 changes: 52 additions & 20 deletions api/posthog_flutter.api.json
Original file line number Diff line number Diff line change
Expand Up @@ -2554,15 +2554,6 @@
"relativePath": "lib/src/posthog_config.dart",
"typeName": "String"
},
{
"isDeprecated": false,
"isExperimental": false,
"isNamed": true,
"isRequired": false,
"name": "onFeatureFlags",
"relativePath": "lib/src/posthog_config.dart",
"typeName": "void Function(PostHogFeatureFlagsLoaded)?"
},
{
"isDeprecated": false,
"isExperimental": false,
Expand Down Expand Up @@ -2877,17 +2868,6 @@
"relativePath": "lib/src/posthog_config.dart",
"typeName": "PostHogBootstrapConfig?"
},
{
"entryPoints": [],
"isDeprecated": false,
"isExperimental": false,
"isReadable": true,
"isStatic": false,
"isWriteable": true,
"name": "onFeatureFlags",
"relativePath": "lib/src/posthog_config.dart",
"typeName": "void Function(PostHogFeatureFlagsLoaded)?"
},
{
"entryPoints": [],
"isDeprecated": false,
Expand Down Expand Up @@ -4942,6 +4922,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,
Expand Down Expand Up @@ -6564,6 +6566,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"
Expand Down
12 changes: 6 additions & 6 deletions example/lib/main.dart
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,6 @@ Future<void> main() async {
final config = PostHogConfig(
'phc_6lqCaCDCBEWdIGieihq5R2dZpPVbAUFISA75vFZow06',
);
config.onFeatureFlags = (loaded) {
debugPrint(
'[PostHog] Feature flags loaded: ${loaded.variants}, '
'errorsLoading: ${loaded.errorsLoading}',
);
};

config.beforeSend = [
(event) {
Expand Down Expand Up @@ -84,6 +78,12 @@ Future<void> main() async {

Future<void> _initAndRun(PostHogConfig config) async {
WidgetsFlutterBinding.ensureInitialized();
Posthog().onFeatureFlags((loaded) {
debugPrint(
'[PostHog] Feature flags loaded: ${loaded.variants}, '
'errorsLoading: ${loaded.errorsLoading}',
);
});
await Posthog().setup(config);
runApp(const MyApp());
}
Expand Down
17 changes: 12 additions & 5 deletions posthog_flutter/MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,22 +213,28 @@ Future<void> disable() async {}
Future<void> optOut() async {}
```

### `onFeatureFlags` and `reloadFeatureFlags()`
### `PostHogConfig.onFeatureFlags` is removed

`PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded`, and `reloadFeatureFlags()` returns a `Future<PostHogFeatureFlagsLoaded>`. It has `flags`, `variants` and `errorsLoading`.
Call `Posthog().onFeatureFlags()` before `setup()`, which also covers the first load. The callback receives a `PostHogFeatureFlagsLoaded`, with `flags`, `variants` and `errorsLoading`, and `reloadFeatureFlags()` now returns a `Future<PostHogFeatureFlagsLoaded>`.

```dart
// Before
final config = PostHogConfig('<project_token>', onFeatureFlags: () {
// ...
});
// or
config.onFeatureFlags = () {
// ...
};
await Posthog().setup(config);

// After
config.onFeatureFlags = (loaded) {
Posthog().onFeatureFlags((loaded) {
if (!loaded.errorsLoading) {
// Use loaded.variants
}
};
});
await Posthog().setup(config);
```

## Behavior changes
Expand Down Expand Up @@ -290,6 +296,7 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an

- An `options` argument on `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`, and `PostHogEvent.options` in `beforeSend`. `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and `product_tour_id` win over their legacy `$` properties. On web, known keys are sent as those legacy properties and other keys are dropped.
- `captureAi` for `$ai_*` events. It returns the event's UUID, or `null` when the event isn't admitted. On web it sends nothing and returns `null`.
- `Posthog().onFeatureFlags()` to get notified after every feature flags load. It returns a `PostHogFeatureFlagsSubscription` you can `unsubscribe()`. You can register it before `WidgetsFlutterBinding.ensureInitialized()`, but other SDK calls, including `setup()`, are skipped with a warning until the binding is initialized.

## Upgrade checklist

Expand All @@ -299,7 +306,7 @@ On web, `PostHogConfig.sendFeatureFlagEvent` is not applied to posthog-js, so an
- [ ] Rename `com.posthog.posthog.API_KEY` to `com.posthog.posthog.PROJECT_TOKEN` in `AndroidManifest.xml` and `Info.plist`.
- [ ] Use Xcode 26 or later.
- [ ] If you run your own reverse proxy or self-host, serve `/i/v1/analytics/events` and `/i/v1/ai/events` first.
- [ ] Update `onFeatureFlags` callbacks to take a `PostHogFeatureFlagsLoaded`.
- [ ] Replace `PostHogConfig.onFeatureFlags` with `Posthog().onFeatureFlags()` before `setup()`.
- [ ] Move anything that reads `version` or `build` on iOS and macOS lifecycle events to `$app_version` and `$app_build`.
- [ ] If you set `sendFeatureFlagEvent = false`, check whether anything relies on `$feature_flag_called` from `getFeatureFlagResult()`.
- [ ] Add `sendFeatureFlagEvent: false` wherever you replace `getFeatureFlagPayload()`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ import com.posthog.PostHogBeforeSend
import com.posthog.PostHogBootstrapConfig
import com.posthog.PostHogCompression
import com.posthog.PostHogConfig
import com.posthog.PostHogFeatureFlagsCallback
import com.posthog.PostHogFeatureFlagsLoaded
import com.posthog.PostHogFeatureFlagsSubscription
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig
import com.posthog.android.internal.getApplicationInfo
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -162,6 +168,8 @@ class PosthogFlutterPlugin :

private var flutterSurveysDelegate: PostHogFlutterSurveysDelegate? = null

private var featureFlagsSubscription: PostHogFeatureFlagsSubscription? = null

override fun onAttachedToEngine(flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
if (bitmapExportExecutor.isShutdown) {
bitmapExportExecutor = Executors.newSingleThreadExecutor()
Expand All @@ -172,6 +180,16 @@ class PosthogFlutterPlugin :
channel = MethodChannel(flutterPluginBinding.binaryMessenger, "posthog_flutter")

this.applicationContext = flutterPluginBinding.applicationContext
// Before initPlugin, so this also catches the first load of a native auto-init.
featureFlagsSubscription?.unsubscribe()
featureFlagsSubscription =
PostHog.onFeatureFlags { loaded ->
Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.")
invokeFlutterMethod(
"onFeatureFlagsCallback",
loaded.toFlutterMap() + ("generation" to flagsGeneration),
)
}
initPlugin()

channel.setMethodCallHandler(this)
Expand Down Expand Up @@ -278,6 +296,7 @@ class PosthogFlutterPlugin :
}

"reset" -> {
updateFlagsGeneration(call)
reset(result)
}

Expand Down Expand Up @@ -358,6 +377,7 @@ class PosthogFlutterPlugin :
}

"close" -> {
updateFlagsGeneration(call)
close(result)
}

Expand Down Expand Up @@ -554,6 +574,7 @@ class PosthogFlutterPlugin :
return
}

updateFlagsGeneration(call)
setupPostHog(args)

result.success(null)
Expand Down Expand Up @@ -841,12 +862,6 @@ class PosthogFlutterPlugin :
)
}
}

onFeatureFlags =
PostHogFeatureFlagsCallback { loaded ->
Log.i("PostHogFlutter", "Android onFeatureFlags triggered. Notifying Dart.")
invokeFlutterMethod("onFeatureFlagsCallback", loaded.toFlutterMap())
}
}

lastBuiltConfig = config
Expand Down Expand Up @@ -987,6 +1002,8 @@ class PosthogFlutterPlugin :

override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
stopOcclusionDetector()
featureFlagsSubscription?.unsubscribe()
featureFlagsSubscription = null
channel.setMethodCallHandler(null)
pushChannelCandidates.remove(channel)
if (activeChannel === channel) {
Expand Down Expand Up @@ -2226,6 +2243,10 @@ class PosthogFlutterPlugin :
}
}

private fun updateFlagsGeneration(call: MethodCall) {
call.argument<Int>("flagsGeneration")?.let { flagsGeneration = it }
}

private fun close(result: Result) {
try {
PostHog.close()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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] {
Expand Down Expand Up @@ -485,6 +511,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)
Expand Down Expand Up @@ -515,6 +542,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
case "distinctId":
distinctId(result)
case "reset":
updateFlagsGeneration(call)
reset(result)
case "enable":
enable(result)
Expand Down Expand Up @@ -547,6 +575,7 @@ public class PosthogFlutterPlugin: NSObject, FlutterPlugin {
case "addExceptionStep":
addExceptionStep(call, result: result)
case "close":
updateFlagsGeneration(call)
close(result)
case "sendMetaEvent":
sendMetaEvent(call, result: result)
Expand Down
Loading
Loading