Skip to content

feat!: capture v1 on every platform, with per-event options and captureAi - #673

Merged
turnipdabeets merged 35 commits into
chore/v6-posthog-ios-4from
feat/v6-desktop-capture-v1
Nov 5, 2026
Merged

turnipdabeets merged 35 commits into
chore/v6-posthog-ios-4from
feat/v6-desktop-capture-v1

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #637 (chore/v6-posthog-ios-4).

💡 Motivation and Context

6.0 moves every Flutter platform except web to capture v1. iOS/macOS and Android get it from posthog-ios 4.0 and posthog-android 4.0 (PostHog/posthog-ios#938, PostHog/posthog-android#881). Windows and Linux don't use a native SDK: the Dart client posted {api_key, batch, sent_at} to /batch/ itself, so this PR moves that transport to capture v1 and makes it behave like the native 4.0 SDKs. Web keeps using the app's posthog-js and is unchanged.

This PR now contains the whole capture v1 stack. Two PRs were merged into it:

Also merged into it since:

It also merges the latest #637 (#662, #694, #697 and main up to 5.58.4).

Per-platform summary

Transport options captureAi
iOS / macOS posthog-ios 4.x, capture v1 sent as-is /i/v1/ai/events via posthog-ios
Android posthog-android 4.x, capture v1 sent as-is /i/v1/ai/events via posthog-android
Windows / Linux Dart client, capture v1 (this PR) sent as-is /i/v1/ai/events via the Dart client, own on-disk queue
Web posthog-js, unchanged known keys mapped to legacy $ properties, others dropped no-op, returns null

Native 4.0 adoption and public API (#649, #674)

  • Require posthog-ios 4.x (Xcode 26) and posthog-android 4.x.
  • PostHogConfig.onFeatureFlags receives a PostHogFeatureFlagsLoaded (enabled flags, values, whether loading failed), and reloadFeatureFlags() returns one. On iOS this is driven by the posthog-ios onFeatureFlags listener, since 4.0 removes the didReceiveFeatureFlags notification.
  • New options parameter on capture, screen, identify, setPersonProperties, alias, group and captureException, and PostHogEvent.options for beforeSend. Known keys (process_person_profile, cookieless_mode, disable_skew_correction, product_tour_id) win over their legacy $ property.
  • New captureAi for $ai_* events. It returns the event's UUID, or null when the event isn't admitted (dropped by beforeSend, oversized, SDK disabled or opted out, or web).
  • New PostHogConfig.captureAiCompression, captureAiMaxQueueSize, captureAiTimeout and captureAiMaxEventBytes. Unset values keep the SDK defaults. They have no effect on web.
  • iOS 4.0 payload decoding changes (posthog-ios#903) and dropped lifecycle version/build (posthog-ios#905) are in the changesets.

Desktop transport (posthog_core_stateless.dart, core/capture_v1.dart)

  • POST /i/v1/analytics/events with Authorization: Bearer <projectToken>, PostHog-Sdk-Info: posthog-flutter/<version>, PostHog-Attempt, PostHog-Request-Id and PostHog-Request-Timestamp. Body is {created_at, batch}, with no api_key or sent_at. Gzip follows config.compression.
  • $session_id/$window_id move to the event root, and $lib/$lib_version are no longer sent as properties. A string ID, "" included, is sent as-is. A non-string is dropped with a warning that names its JSON type, never the value.
  • Event options go into the v1 event's options unchanged, unknown keys included, with null values stripped. The legacy $process_person_profile, $cookieless_mode, $ignore_sent_at and $product_tour_id properties are always removed and only fill an option that is unset.
  • Per-event results: ok, warning, drop, limited, unknown results and events missing from the results leave the queue. Only retry events are sent again. While a retry is pending, the next request sends exactly those events alone, keeping the request ID and created_at and incrementing PostHog-Attempt; newer events follow as a new request. If one of them is gone (evicted, deleted), the retry starts over as a new request at attempt 1 (fix(desktop): resend a capture v1 retry alone to keep its request identity #704, matching posthog-android 4.0 and the server v1 SDKs). Drop/retry logging is a count, with no UUIDs or payloads.
  • A 2xx whose results can't be read (malformed, or the body fails or times out after the status arrived) counts as delivered, because a resend would store the events twice.
  • Only same-origin 307/308 redirects are followed, at most 5 hops, with the same body and headers. Any other redirect is terminal (before, desktop retried 3xx).
  • A batch closes at maxBatchSize events or 5 MiB of serialized events, whichever comes first, as on iOS and Android. An event over 5 MiB goes alone.

Retries, backoff and flushing (#678)

  • Retried statuses: network errors, 404, 408, 429, 500, 502, 503, 504. 404 usually means a misconfigured proxy and 429 an overloaded Envoy, so dropping would lose events that can still be delivered (ports fix: retry capture requests that get 404 or 429 posthog-go#395). There is no /batch fallback on 404, as in posthog-android 4.0 and the server v1 SDKs: events stay queued and a warning is printed once, also without debug.
  • Backoff: a transient failure, or a 2xx that asks for retries, no longer resends inside the flush (it used to try 3 times, 3 s apart). The queue pauses 1 s, doubling to 30 s, with ±25% jitter, until a batch is delivered or dropped. Retry-After is a floor under the backoff (not a replacement), capped at 30 s (it had no cap).
  • Request timeout: a request fails only after 10 s without progress (connect, a 64 KiB body chunk, response headers, a response body chunk), not 10 s for the whole request, so a large batch on a slow uplink isn't stuck forever.
  • 413 halves the batch size and flushAt and ends the flush. A single oversized event is dropped. No backoff, as on iOS.
  • Byte flush trigger: the queue also flushes once 5 MiB of serialized events is queued, not only at flushAt.

Desktop captureAi, property order and person processing (#679)

  • AI endpoint: same wire format and send loop as analytics, sent to /i/v1/ai/events. Its per-endpoint state lives in a _CaptureLane, so the AI lane has its own retry identity, timers, backoff and 413 state, and a failing AI request doesn't hold back analytics (or the reverse). capture never sends to the AI endpoint; a captureAi name without $ai_ gets a debug log and is still sent, like native.
  • AI queue: on disk in posthog_ai_queue/, persisted across restarts, up to captureAiMaxQueueSize events (100) and 50 MiB, oldest dropped first. An event over captureAiMaxEventBytes (default and cap 8 MiB + 64 KiB, serialized, before gzip) is dropped and captureAi returns null; the log names only the event and its size. Requests use captureAiCompression and fail after captureAiTimeout (60 s) without progress.
  • Property order: SDK-set properties first (context, $timezone, $lib, flag properties, $recording_status, $session_id, $is_identified, $sdk_debug_*), then the current-screen property, then registered properties, then the event's own. A registered or event value now wins over an SDK value, for that event only.
  • beforeSend (Dart, synchronous since feat!: make beforeSend callbacks synchronous #686) runs on the fully built event, sees and can change every SDK property and option, and the event is queued as it leaves it. The timestamp is taken before the callbacks run. SDK-internal events still skip the Dart callbacks. Exception steps are still attached after beforeSend.
  • Person processing is sent as options.process_person_profile: false only while it's off and nothing else sets it, instead of a $process_person_profile property on every event (sdk-specs "Unset control options are omitted").

Upgrade from 5.x

Queued events are stored in the 5.x /batch message shape, and the v1 shape is built at send time. Events that 5.x left in posthog_queue/ are sent through v1 after the upgrade, with $lib stripped, $session_id lifted to the root and $process_person_profile moved into options. A test covers this with a literal 5.56.2 queue file. The retry identity lives only in memory, so a retry after a restart is a new request.

Divergences from sdk-specs

  • 413 halves the batch instead of being terminal, as on iOS and Android.
  • No attempt limit: retries back off 1 s → 30 s until delivered, as on iOS/Android, not the server SDKs' give-up-after-3.
  • No historical-migration mode, as on iOS and Android.
  • captureAi takes no uuid and returns the generated one, like the native mobile SDKs (the capture-ai spec targets server SDKs).
  • The capture spec (step 4) lists $process_person_profile among SDK-set properties. Desktop follows native 4.0 and sends it as an option only when it's off.
  • The request timeout is an idle timeout as close to OkHttp/URLSession as dart:io allows: it can't see bytes still in the kernel send buffer.

Breaking changes

Change Platforms Who notices
Endpoint moves to /i/v1/analytics/events (and /i/v1/ai/events) with Bearer auth, no fallback iOS, macOS, Android, Windows, Linux Reverse proxies, allowlists and self-hosted instances must serve the new paths. On desktop a 404 keeps events queued and retried, a 403/405 drops them
posthog-ios 4.x (Xcode 26) and posthog-android 4.x iOS, macOS, Android Apps pinning the 3.x native SDKs
onFeatureFlags takes a PostHogFeatureFlagsLoaded; reloadFeatureFlags() returns one all Callbacks written as () { ... }
3xx is terminal and Retry-After is capped at 30 s Windows, Linux Redirecting or rate-limited setups
Registered and event properties win over SDK properties; beforeSend sees SDK properties; person processing sent as an option only when off Windows, Linux Apps that set SDK-named properties or inspect events in beforeSend

Left out

💚 How did you test it?

  • flutter test in posthog_flutter after merging the latest chore!: Flutter Major Release v6 #637 (Nov 3): 1463 passed, 1 skipped. dart analyze .: no issues. dart format --set-exit-if-changed .: 0 changed. scripts/check-api-dart.sh: snapshot up to date.
  • test/core/capture_v1_test.dart: envelope and headers, option hoisting and precedence, session/window ID lifting, per-event results, retry identity, captureRetryDelay (doubling, cap, jitter, Retry-After floor and cap), unreadable 2xx, oversized event on 413, 404 retried without falling back to /batch, same-origin 307 and the 6th-redirect cutoff, a literal 5.56.2 queue file sent through v1.
  • test/core/capture_ai_test.dart (local server): AI endpoint, headers and payload; $ai_ events from capture stay on analytics; separate compression and queue size; size limit and its log; 50 MiB cap keeps the newest; 5 MiB flush; persistence across clients; 400 and per-event retry on the AI lane; AI and analytics backing off independently.
  • queue_flush_test / requests_test: retried vs terminal statuses, the 1/2/4/8/16/30 s schedule and ±25% jitter, Retry-After on 429/503, a delivered batch resetting the backoff, the 404 warning once, the idle timeout (slow upload finishes past 10 s, stalled upload aborted at 10 s, trickling response), 413 halving, 5 MiB batch cap and byte flush trigger, a 2xx whose body times out not being resent.
  • Desktop platform tests: captureAi through beforeSend, options passthrough (unknown and nested keys, on identify/setPersonProperties/group/alias), beforeSend seeing and changing SDK properties and options, /flags person properties only from what beforeSend keeps, the new property order, person processing on options, and getFeatureFlagResult following config.sendFeatureFlagEvent.
  • Android plugin tests for options and captureAi channel serialization (EventOptionsChannelTest.kt, PosthogFlutterPluginTest.kt).
  • example/integration_test/desktop_test.dart fake server serves the v1 path. Not run on a Windows or Linux device, and nothing sent to PostHog Cloud from desktop.

🧪 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: log request paths on the local server. capture should go through capture v1, captureAi should reach the AI endpoint, and per-event options should be applied.

📝 Checklist

If releasing new changes

  • Ran pnpm changeset to generate a changeset file: entries are in .changeset/v6-major-release.md

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

  • Built with Claude Code from the posthog-ios #938/#979 and posthog-android #881/#897 descriptions and diffs (feat/v4-capture-v1, feat/v4-capture-ai), fix: retry capture requests that get 404 or 429 posthog-go#395, and the sdk-specs capture, capture-ai and capture v1 yaml-parity features.
  • Decisions: retried 404 with no /batch fallback; converting the queue at send time instead of migrating it; replacing desktop's in-flush retries with the native jittered backoff; one send loop with a lane per endpoint instead of a second transport for AI.

TODO before release

🤖 Generated with Claude Code

Windows and Linux post to /i/v1/analytics/events with bearer auth, per-event results and the v1 retry rules.
@turnipdabeets
turnipdabeets requested a review from a team as a code owner October 26, 2026 18:57
@turnipdabeets turnipdabeets self-assigned this Oct 26, 2026

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 027330f: 1 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.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

posthog-flutter Compliance Report

Date: 2026-11-05T14:46:05.654440+00:00
Duration: 369599ms

✅ All Tests Passed!

232/232 tests passed


Capture_V1 Tests

✅ 105/105 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 198ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 122ms
Required Headers.Has Authorization Bearer Header ✅ 117ms
Required Headers.Has Content Type Json ✅ 119ms
Required Headers.Has Posthog Sdk Info Format ✅ 116ms
Required Headers.Has Posthog Attempt Header ✅ 115ms
Required Headers.Has Posthog Request Id ✅ 116ms
Required Headers.Has Posthog Request Timestamp ✅ 116ms
Required Headers.Has User Agent ✅ 117ms
Body Format.Body Has Created At And Batch ✅ 116ms
Body Format.No Api Key In Body ✅ 115ms
Body Format.No Sent At In Body ✅ 114ms
Event Format.Event Has Required Root Fields ✅ 115ms
Event Format.Event Uuid Is Valid ✅ 115ms
Event Format.Event Timestamp Is Rfc3339 ✅ 115ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 115ms
Event Format.Distinct Id Is String ✅ 116ms
Event Format.Distinct Id At Root Not Properties ✅ 114ms
Event Format.Custom Properties Preserved ✅ 115ms
Event Format.Set Properties Preserved ✅ 117ms
Event Format.Set Once Properties Preserved ✅ 115ms
Event Format.Groups Properties Preserved ✅ 114ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 115ms
Event Format.Event Has Required Root Fields Batch ✅ 118ms
Event Format.Event Uuid Is Valid Batch ✅ 118ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 118ms
Event Format.Distinct Id Is String Batch ✅ 118ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 119ms
Event Format.Custom Properties Preserved Batch ✅ 121ms
Event Format.Set Properties Preserved Batch ✅ 118ms
Event Format.Set Once Properties Preserved Batch ✅ 118ms
Event Format.Groups Properties Preserved Batch ✅ 118ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 118ms
Batch Behavior.Multiple Events In Single Batch ✅ 122ms
Batch Behavior.Batch Envelope Smoke ✅ 120ms
Batch Behavior.Flush With No Events Sends Nothing ✅ 107ms
Batch Behavior.Flush At Triggers Batch ✅ 1012ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 117ms
Deduplication.Generates Unique Uuids ✅ 122ms
Deduplication.Different Events Same Content Different Uuids ✅ 116ms
Deduplication.Preserves Uuid On Retry ✅ 5120ms
Deduplication.Preserves Timestamp On Retry ✅ 5121ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5124ms
Deduplication.No Duplicate Events In Batch ✅ 124ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 114ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 10124ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 5121ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2227ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 5120ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 114ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 118ms
Response Format Validation.Success No Retry After When All Ok ✅ 116ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 116ms
Response Format Validation.Success No Retry After When Drop Only ✅ 118ms
Response Format Validation.Response Echoes Request Id ✅ 113ms
Retry Behavior.Retries On 408 ✅ 5119ms
Retry Behavior.Retries On 500 ✅ 5120ms
Retry Behavior.Retries On 503 ✅ 5118ms
Retry Behavior.Retries On 504 ✅ 5120ms
Retry Behavior.Retries On 404 ✅ 5121ms
Retry Behavior.Retries On 429 ✅ 5120ms
Retry Behavior.Retries On 502 ✅ 5129ms
Retry Behavior.Retryable Errors Have Retry After ✅ 2117ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 8122ms
Retry Behavior.Does Not Retry On 400 ✅ 2116ms
Retry Behavior.Does Not Retry On 401 ✅ 2116ms
Retry Behavior.Does Not Retry On 402 ✅ 2117ms
Retry Behavior.Does Not Retry On 413 ✅ 2117ms
Retry Behavior.Does Not Retry On 415 ✅ 2117ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 2117ms
Retry Behavior.Implements Backoff ✅ 12118ms
Partial Batch Handling.Handles 200 Full Success ✅ 2117ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3121ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3120ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3119ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 5122ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 5122ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 5125ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 5122ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 5123ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 5122ms
Partial Batch Handling.Respects Retry After On Partial ✅ 5122ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3119ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3124ms
Compression.Sends Gzip Content Encoding ✅ 116ms
Compression.No Content Encoding When Disabled ✅ 113ms
Compression.Compressed Body Is Decompressible ✅ 113ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 2116ms
Event Options.Cookieless Mode Override ✅ 114ms
Event Options.Disable Skew Correction Override ✅ 114ms
Event Options.Process Person Profile Override ✅ 113ms
Event Options.Product Tour Id Override ✅ 114ms
Event Options.Unset Options Omitted ✅ 113ms
Event Options.Options Override In Batch ✅ 116ms
Event Options.Unknown Option Passes Through ✅ 113ms
Event Options.Option Value Is Not Converted ✅ 114ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 114ms
Event Options.Option Wins Over Legacy Property ✅ 113ms
Event Options.Legacy Property Fills Unset Option ✅ 113ms
Event Options.Null Option Falls Back To Legacy Property ✅ 113ms
Property Layers.Caller Property Beats Registered Property ✅ 113ms
Property Layers.Before Send Runs Last ✅ 114ms
Fail Open.Empty Api Key Sends Nothing ✅ 1109ms
Fail Open.Personal Api Key Sends Nothing ✅ 1109ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 113ms

Capture_Ai_V1 Tests

✅ 110/110 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 115ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 112ms
Endpoint And Method.Capture Does Not Reroute Ai Named Events ✅ 114ms
Endpoint And Method.Capture Ai Does Not Reroute Non Ai Events ✅ 114ms
Lane Isolation.Failing Ai Lane Does Not Delay Analytics ✅ 5126ms
Required Headers.Has Authorization Bearer Header ✅ 114ms
Required Headers.Has Content Type Json ✅ 113ms
Required Headers.Has Posthog Sdk Info Format ✅ 113ms
Required Headers.Has Posthog Attempt Header ✅ 113ms
Required Headers.Has Posthog Request Id ✅ 113ms
Required Headers.Has Posthog Request Timestamp ✅ 113ms
Required Headers.Has User Agent ✅ 113ms
Body Format.Body Has Created At And Batch ✅ 113ms
Body Format.No Api Key In Body ✅ 113ms
Body Format.No Sent At In Body ✅ 113ms
Event Format.Event Has Required Root Fields ✅ 113ms
Event Format.Event Uuid Is Valid ✅ 113ms
Event Format.Event Timestamp Is Rfc3339 ✅ 113ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 113ms
Event Format.Distinct Id Is String ✅ 113ms
Event Format.Distinct Id At Root Not Properties ✅ 113ms
Event Format.Custom Properties Preserved ✅ 113ms
Event Format.Set Properties Preserved ✅ 113ms
Event Format.Set Once Properties Preserved ✅ 113ms
Event Format.Groups Properties Preserved ✅ 113ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 113ms
Event Format.Event Has Required Root Fields Batch ✅ 116ms
Event Format.Event Uuid Is Valid Batch ✅ 116ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 116ms
Event Format.Distinct Id Is String Batch ✅ 118ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 116ms
Event Format.Custom Properties Preserved Batch ✅ 116ms
Event Format.Set Properties Preserved Batch ✅ 117ms
Event Format.Set Once Properties Preserved Batch ✅ 116ms
Event Format.Groups Properties Preserved Batch ✅ 116ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 116ms
Batch Behavior.Multiple Events In Single Batch ✅ 120ms
Batch Behavior.Batch Envelope Smoke ✅ 118ms
Batch Behavior.Flush At Triggers Batch ✅ 1011ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 113ms
Deduplication.Generates Unique Uuids ✅ 120ms
Deduplication.Different Events Same Content Different Uuids ✅ 115ms
Deduplication.Preserves Uuid On Retry ✅ 5118ms
Deduplication.Preserves Timestamp On Retry ✅ 5120ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5122ms
Deduplication.No Duplicate Events In Batch ✅ 121ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 115ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 10124ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 5119ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2226ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 5119ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 114ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 118ms
Response Format Validation.Success No Retry After When All Ok ✅ 116ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 117ms
Response Format Validation.Success No Retry After When Drop Only ✅ 117ms
Response Format Validation.Response Echoes Request Id ✅ 112ms
Retry Behavior.Retries On 408 ✅ 5118ms
Retry Behavior.Retries On 500 ✅ 5119ms
Retry Behavior.Retries On 503 ✅ 5120ms
Retry Behavior.Retries On 504 ✅ 5119ms
Retry Behavior.Retries On 404 ✅ 5120ms
Retry Behavior.Retries On 429 ✅ 5119ms
Retry Behavior.Retries On 502 ✅ 5119ms
Retry Behavior.Retryable Errors Have Retry After ✅ 2116ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 8122ms
Retry Behavior.Does Not Retry On 400 ✅ 2117ms
Retry Behavior.Does Not Retry On 401 ✅ 2116ms
Retry Behavior.Does Not Retry On 402 ✅ 2117ms
Retry Behavior.Does Not Retry On 413 ✅ 2116ms
Retry Behavior.Does Not Retry On 415 ✅ 2116ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 2116ms
Retry Behavior.Implements Backoff ✅ 12126ms
Partial Batch Handling.Handles 200 Full Success ✅ 2116ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3121ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3119ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3118ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 5116ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 5117ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 5123ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 5121ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 5121ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 5121ms
Partial Batch Handling.Respects Retry After On Partial ✅ 5120ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3119ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3122ms
Compression.Sends Gzip Content Encoding ✅ 113ms
Compression.No Content Encoding When Disabled ✅ 113ms
Compression.Compressed Body Is Decompressible ✅ 112ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 2115ms
Event Options.Cookieless Mode Override ✅ 113ms
Event Options.Disable Skew Correction Override ✅ 113ms
Event Options.Process Person Profile Override ✅ 112ms
Event Options.Product Tour Id Override ✅ 112ms
Event Options.Unset Options Omitted ✅ 112ms
Event Options.Options Override In Batch ✅ 116ms
Event Options.Unknown Option Passes Through ✅ 113ms
Event Options.Option Value Is Not Converted ✅ 115ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 117ms
Event Options.Option Wins Over Legacy Property ✅ 113ms
Event Options.Legacy Property Fills Unset Option ✅ 112ms
Event Options.Null Option Falls Back To Legacy Property ✅ 112ms
Event Size.Event Over Ceiling Is Not Sent ✅ 4004ms
Event Size.Over Ceiling Drop Is Reported Or Logged Without Content ✅ 2184ms
Event Size.Batches Close Before Byte Target ✅ 6105ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 116ms
Property Layers.Caller Property Beats Registered Property ✅ 113ms
Property Layers.Before Send Runs Last ✅ 112ms
Fail Open.Empty Api Key Sends Nothing ✅ 1109ms
Fail Open.Personal Api Key Sends Nothing ✅ 1110ms

Feature_Flags Tests

✅ 17/17 tests passed

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

@eli-r-ph

Copy link
Copy Markdown

The compliance adapter still declares capabilities ['capture_v0', 'encoding_gzip'], so the harness runs only the legacy capture suite against the desktop code this PR moves to v1; the 45/45 here is that legacy suite. Should the adapter declare capture_v1 (and capture_ai_v1 once #674 lands) so the v1 suites run on desktop? The v1 suites themselves get a refresh before release in a separate harness change, so a pin bump can come with that.

Counts only: dropped and rate-limited events were deleted from the queue
with no diagnostic, even in debug mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@dustinbyrne dustinbyrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed after the logging update. The rejection-count warning resolves the earlier concern, and the desktop v1 transport, retry handling and persisted-queue conversion look sound.

AI-assisted review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eli-r-ph

Copy link
Copy Markdown

Two small parity asks for the desktop sender. Analytics batches here are capped by count only (50); iOS and Android also close a batch at 5 MiB of serialized events, checking before appending, which keeps requests under proxy and capture limits. Could desktop do the same? Also, desktop retries use a fixed 3 s wait without jitter, while iOS and Android use 1 s doubling with jitter. That's fine for 6.0 as a recorded difference, unless it's easy to align now.

A batch closed only at maxBatchSize events, so large events could push a
request past proxy and capture body limits. Each event's serialized size is
now checked before it joins the batch; an event that doesn't fit starts the
next one, and an event over the limit goes alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets

turnipdabeets commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor Author

@eli-r-ph Thanks! Desktop batches now also close at 5 MiB of serialized events, checked before each event joins, so an oversized event goes alone (e7eebba, with tests). The retry pacing is in #678, which reworks it on top of this: desktop now backs off like iOS/Android (1 s doubling to 30 s, ±25% jitter, Retry-After as a floor, partial retries advance it) in ed36592. So the backoff matches native and isn't a 6.0 difference anymore.

* fix: retry desktop capture v1 requests that get 404 or 429

A 404 usually means a misconfigured proxy and a 429 an overloaded Envoy; both are worth retrying with the same backoff, Retry-After handling and retry budget. Redirects stay terminal.

* fix: back off across failed desktop flushes and warn once on a capture 404

After a batch fails its retries, later flushes make one attempt each and
pause 6s doubling to 30s until a batch is delivered. Before, every flush,
including the one each capture starts at flushAt, sent 4 requests, so a
missing capture route kept resending the batch.

A 404 prints one warning per client even without debug, naming the URL
and the path a proxy or self-hosted instance must serve.

* fix: leave the host out of the capture 404 warning

A host with proxy credentials in its userinfo would print them to app logs.

* fix(desktop): back off capture v1 retries like posthog-ios and posthog-android

A transient failure or a 2xx whose per-event results ask to retry no longer
resends within the flush (3 tries, 3 s apart). Each one pauses the queue for
1 s doubling to 30 s, with ±25% jitter from an injectable source. A
Retry-After is a floor applied after the jitter, capped at 30 s, instead of
replacing the backoff, so `Retry-After: 1` no longer resends every 3 s.
A delivered or dropped batch resets the backoff.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): time out capture requests on inactivity, not on total duration

The 10 s whole-call timeout could fail a large batch on a slow uplink on
every attempt. A request now fails only after 10 s without progress:
connecting (HttpClient.connectionTimeout), the socket taking a 64 KiB body
chunk, the response headers, or a response body chunk. This is the closest
dart:io gets to the per-read/per-write idle timeouts of OkHttp and
URLSession: like them, it can't see the bytes still in the kernel send
buffer, so the wait for headers starts once the last chunk is handed over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): halve flushAt with the batch size on 413 and end the flush

A 413 halved only the batch size and resent at once in the same flush. Like
posthog-ios and posthog-android, it now also halves flushAt, kept within
the batch size, and the smaller batches go out with the next flush (the
next capture over flushAt, or the periodic flush). No backoff is added:
posthog-ios ends the flush without one; posthog-android pauses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): flush once 5 MiB of events are queued

Like posthog-ios and posthog-android, a full capture v1 request's worth of
queued bytes (captureV1MaxBatchBytes) now flushes as flushAt does, so a few
large events go out before the queue starts dropping them. The file queue
keeps each event's serialized size: measured when it is added, and read
from the file sizes when a later process loads the queue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): cap the response body read at 30 seconds

A body that trickles in more often than the 10 s idle timeout reset it
forever, holding the flush. The body now also fails after 30 s in total.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 22d3e0e: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

turnipdabeets added a commit that referenced this pull request Oct 28, 2026
#673's head already matches #678's branch, merged in the previous commit;
this records #673's squashed #678 as merged so #679 can target #673.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
turnipdabeets and others added 2 commits October 29, 2026 17:05
…d options passthrough (#679)

* chore!: adopt posthog-ios 4.0

- Require posthog-ios 4.x.
- Adapt to the reloadFeatureFlags(_:) callback that now passes a
  PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913).
- Note the payload decoding changes from PostHog/posthog-ios#903.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changeset): note posthog-ios 4.0 drops lifecycle version and build

PostHog/posthog-ios#905 removes the legacy version/build properties from
lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener

posthog-ios 4.0 removes the didReceiveFeatureFlags notification.

* chore!: adopt posthog-android 4.0

* feat: add per-event capture options and captureAi

Passes options and captureAi through to posthog-ios and posthog-android 4.0; Windows, Linux and web send known options as their legacy properties.

* feat: add captureAi queue and request settings to PostHogConfig

Add captureAiCompression, captureAiMaxQueueSize, captureAiTimeout and
captureAiMaxEventBytes. Set values are sent to native setup and applied to
the posthog-ios and posthog-android config; unset values are omitted so the
native defaults apply. They have no effect on Windows, Linux and web.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: spell out when captureAi returns null

null means the event wasn't admitted: dropped by beforeSend, oversized on
iOS and macOS, SDK disabled or opted out, or an unsupported platform. On
Windows, Linux and web captureAi is a no-op that sends nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: captureAi returns null for an oversized event on Android too

posthog-android now checks the size before queuing (f46a9711).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: retry desktop capture v1 requests that get 404 or 429

A 404 usually means a misconfigured proxy and a 429 an overloaded Envoy; both are worth retrying with the same backoff, Retry-After handling and retry budget. Redirects stay terminal.

* fix: back off across failed desktop flushes and warn once on a capture 404

After a batch fails its retries, later flushes make one attempt each and
pause 6s doubling to 30s until a batch is delivered. Before, every flush,
including the one each capture starts at flushAt, sent 4 requests, so a
missing capture route kept resending the batch.

A 404 prints one warning per client even without debug, naming the URL
and the path a proxy or self-hosted instance must serve.

* fix: leave the host out of the capture 404 warning

A host with proxy credentials in its userinfo would print them to app logs.

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664)

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags

onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes.

* fix: complete the web reloadFeatureFlags with the reloaded flags

Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back.

* chore: use PostHogFeatureFlagsCallback from posthog-android 4.0

* chore: fix ktlint function-signature

* fix: await posthog-js reloadFeatureFlagsAsync on web

The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js.

* docs: pass the loaded flags in the setup example

* docs: drop best-effort web note from the person and group property methods

* fix(web): wait for posthog-js flags retries before reporting a reload failure

posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed.

* docs: note where onFeatureFlags and errorsLoading differ on Android and web

* docs: describe the older posthog-js reload timeout as the full retry budget

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* feat(desktop): send event options unchanged in the capture v1 event

On Windows and Linux, the options of capture, screen, captureException,
identify, setPersonProperties, alias and group now go into the event's
capture v1 `options` as they are, unknown keys included, instead of being
mapped to legacy `$` properties. An option still wins over its legacy
property, which is moved into `options` only when the option is unset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(desktop): build event properties in the native 4.0 order

On Windows and Linux, an event's properties are now the ones the SDK
sets, then the registered ones, then the event's own, each winning over
the ones before, and the Dart beforeSend callbacks run after that merge.
They see and can change every property and option the SDK adds, and the
event is queued as they leave it. A caller or registered value changes
that event only.

Person processing is no longer a `$process_person_profile` property: the
event carries `process_person_profile: false` in its options only while
person processing is off and neither an option nor a property sets it,
and omits it otherwise. The event's timestamp is taken before the
callbacks run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): back off capture v1 retries like posthog-ios and posthog-android

A transient failure or a 2xx whose per-event results ask to retry no longer
resends within the flush (3 tries, 3 s apart). Each one pauses the queue for
1 s doubling to 30 s, with ±25% jitter from an injectable source. A
Retry-After is a floor applied after the jitter, capped at 30 s, instead of
replacing the backoff, so `Retry-After: 1` no longer resends every 3 s.
A delivered or dropped batch resets the backoff.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): time out capture requests on inactivity, not on total duration

The 10 s whole-call timeout could fail a large batch on a slow uplink on
every attempt. A request now fails only after 10 s without progress:
connecting (HttpClient.connectionTimeout), the socket taking a 64 KiB body
chunk, the response headers, or a response body chunk. This is the closest
dart:io gets to the per-read/per-write idle timeouts of OkHttp and
URLSession: like them, it can't see the bytes still in the kernel send
buffer, so the wait for headers starts once the last chunk is handed over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): halve flushAt with the batch size on 413 and end the flush

A 413 halved only the batch size and resent at once in the same flush. Like
posthog-ios and posthog-android, it now also halves flushAt, kept within
the batch size, and the smaller batches go out with the next flush (the
next capture over flushAt, or the periodic flush). No backoff is added:
posthog-ios ends the flush without one; posthog-android pauses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(desktop): send captureAi events to the capture v1 AI endpoint

On Windows and Linux, captureAi now builds the event like capture, runs
the Dart beforeSend callbacks, and queues it on disk apart from other
events, in posthog_ai_queue/. It is sent to /i/v1/ai/events with the
same wire format, batching, retry rules and backoff as analytics events,
and returns the event's uuid, or null when the event isn't queued:
dropped by beforeSend, opted out, or over the size limit.

- A serialized event over captureAiMaxEventBytes, capped at and by
  default 8 MiB plus 64 KiB, measured before compression, is dropped with
  a log line naming only the event and its size.
- The queue keeps captureAiMaxQueueSize events (100 by default) and at
  most 50 MiB, dropping the oldest first, and flushes as soon as 5 MiB
  is queued.
- Requests use captureAiCompression (gzip by default) and are bounded by
  captureAiTimeout (60 seconds by default).
- Each endpoint keeps its own retry identity, timers, backoff and 413
  batch size, so a failing AI request doesn't hold back other events.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: describe desktop captureAi, options and property order in changesets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): flush once 5 MiB of events are queued

Like posthog-ios and posthog-android, a full capture v1 request's worth of
queued bytes (captureV1MaxBatchBytes) now flushes as flushAt does, so a few
large events go out before the queue starts dropping them. The file queue
keeps each event's serialized size: measured when it is added, and read
from the file sizes when a later process loads the queue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): feed flags the person properties beforeSend keeps

$set/$set_once were stored for flag evaluation while the event was
prepared, before the beforeSend callbacks ran, so a redacted value or a
dropped event still reached the next /flags request. They are now taken
from the event as it is queued.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep properties beforeSend removes off the queued event

The payload builder merged the common properties ($feature/<key>,
$active_feature_flags, $recording_status, $lib) under every event again,
so a property the callbacks removed came back. Every core path already
builds them into the event's properties, so the payload adds nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf(desktop): size the capture batch before reading queued events

The flush peeked up to maxBatchSize events, decoding each one, before
the 5 MiB batch cap picked the few it sends. With 8 MiB AI events queued
that read far more than one request carries, on the UI isolate. The
queue now applies the cap from its tracked per-event sizes before it
reads an event, always keeping the first, so only the batch is decoded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): release delivered payloads after each capture v1 batch

A flush that kept finding queued events held every delivered payload
until it ended. Emit flush per batch so multi-megabyte AI events are
released as soon as they are sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): turn on person processing only for events beforeSend keeps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): give beforeSend a deep copy of the event properties

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: limit the capture v1 migration note to native and desktop platforms

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): note beforeSend cannot change $lib or $lib_version

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): cap the response body read at 30 seconds

A body that trickles in more often than the 10 s idle timeout reset it
forever, holding the flush. The body now also fails after 30 s in total.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): warn when captureAiMaxEventBytes is over the ceiling

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style: format the merged fetch attempt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: update SDK compliance harness to 1.26.0 (#680)

* ci: update SDK compliance harness to 1.25.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(compliance): bump the test harness to 1.26.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): check registered person processing before caching identify

* fix(desktop): keep a legacy $set in properties for beforeSend to remove

* fix(desktop): recompute person processing from the properties beforeSend keeps

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed cf0d1e2: 3 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

@turnipdabeets turnipdabeets changed the title feat!: send Windows and Linux events through capture v1 feat!: capture v1 on every platform, with per-event options and captureAi Oct 29, 2026
turnipdabeets and others added 2 commits October 29, 2026 17:14
…properties

An anonymous event that a callback gave $set kept the SDK's
process_person_profile: false, so PostHog ignored the person update.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An AI event dropped for its size still turned on person processing and
fed its person properties to /flags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@eli-r-ph eli-r-ph left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

events.onAny((event, payload) => logger.info(event, payload));

In debug mode this prints every captured and flushed event with all its properties, AI prompts included. Could debug logs show only the event name, lane and size?


This still passes RRStyle(), which posthog-android #908 removes, so Android stops compiling once #908 ships. #649's last two commits (#684) fix it.

final processedEvent = await _runBeforeSend(

On iOS, macOS and Android the Dart beforeSend still runs before the native SDK adds its properties, so it can't see or change them. #682 fixes this, so it needs to ship in 6.0.

// Re-added after the callbacks, so one that rebuilds the property map

Putting $screen_name back after beforeSend means a hook can't remove it, and a non-string value throws and drops the event. Could this send what the hook leaves?

/// Platform context (OS, app, device) attached to every event. It wins

Since the property-order change, platform context loses to registered and event properties, so this comment is out of date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
turnipdabeets and others added 4 commits November 3, 2026 09:02
…t/v6-desktop-capture-v1

# Conflicts:
#	posthog_flutter/darwin/posthog_flutter.podspec
…I isolate (#688)

* perf(desktop): move queue file work and request compression off the UI isolate

On Windows and Linux the Dart client encoded, measured, wrote and read
queued events and gzipped request bodies on the UI isolate. An 8 MB AI
event stalled it for over 200 ms. A long-lived background isolate now
does that work, in order, falling back to the calling isolate if it
cannot start or exits.

- The queue keeps its order and counts on the UI isolate; an event
  takes its place at once and is measured by the worker.
- captureAi waits for the worker's size verdict, and applies person
  properties only if the user is unchanged.
- close() waits for pending writes and deletes, so the next client
  neither misses an event nor sends one again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): wait only for writes preceding a queue peek

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): exclude AI events being measured from queue eviction

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep selecting queue events past unreadable files

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep person properties set while an AI event is measured

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): TEMP diagnose the hanging test step

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): remove the temporary test step diagnostics

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): recheck flushAt once a queued event is written

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): skip the snapshot write for AI events without person properties

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep the directory locked until queue file work is done

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): don't throw from settled while only one queue has file work

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): bound how long close waits for queue file work

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): bound the queue writes given to the worker

Captures outpacing the worker kept every event in memory until it was written. Writes past a small window now wait in the queue, where eviction can cancel them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): finish queue file work before temp directories are deleted

Windows can't delete a directory with a file still open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): complete capture once the event is written, and survive failed queue jobs

An awaited capture is on disk again, so awaiting it before exit() keeps the event. A failed write job keeps the event in memory instead of wedging the queue, a flush waits for events still being written, and a failed job during close no longer stops the next setup. Records the unawaited-capture timing as a breaking change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): complete identify, alias, group and setPersonProperties once written

Awaiting them before exit() keeps their events, like capture. Without this, identify lost its event for good, since the new id is already saved. Also tests the awaits and the failed close properly, and records the change in the changeset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(desktop): state what awaiting a call keeps, and trim comments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): guard deferred AI person properties with a reset generation

Identifying an anonymous user keeps the person, so comparing distinct ids
discarded their properties, and let pre-reset ones back when the same id
was identified again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): log when queue work falls back to the UI isolate

The frame drops the worker removes would otherwise return with no sign of why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(desktop): keep the gzip choice with the encoded body

The bytes and the Content-Encoding header could otherwise disagree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): release the shared worker's logger when its client closes

The logger retains the client, and with it any events kept in memory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): avoid a protected member in the logger release test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #688 release notes into the 6.0 docs

* fix(desktop): keep events after an unmeasured AI event person-processed

An AI event with $set turned on person processing only once the worker had
measured it, so an unawaited captureAi followed by capture sent the next
event personless.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): limit AI events waiting to be written by estimated bytes (#693)

* fix(desktop): limit AI events waiting to be written by estimated bytes

The count limit alone let unawaited captures of large events hold over a
GiB in memory. These events would mostly be evicted by the 50 MiB queue
limit once measured, so they are now evicted before that, and captureAi
reports them as not queued.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): count containers in the waiting-bytes estimate

A long list of empty strings otherwise counts as nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf(desktop): keep a running total of waiting bytes

Rescanning every waiting event on each capture is quadratic on the UI
isolate in a burst of small events.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #693 release notes into the 6.0 docs

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): cover calls made while the queue worker holds its reply (#700)

GatedWorker can now hold reads and request bodies too. The new tests make a
call while the worker has not answered, then release it: captures, evictions,
reset and close during a flush's read or encode, and AI events measured after
close or dropped for their size during a flush.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat!: make beforeSend callbacks synchronous

Event and log beforeSend callbacks no longer return FutureOr, matching the
native SDKs and the before-send-hook spec. The event is handed to the SDK in
the same call, so calls made right after an un-awaited capture can no longer
reach the SDK first, on every platform including Windows and Linux.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the call queue on iOS, macOS and Android

With #682 and beforeSend set, an event takes two native calls. Without the
queue, an optOut(), close() or setup() made right after capture() reaches
native between them and the event is lost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(android): restore the screenshot scale expectation lost in the main merge

* fix(web): hand feature events to posthog-js before yielding

Without CallOrder the await on the flag lookup let a reset() made right after
an un-awaited captureFeatureView or captureFeatureInteraction overtake it, so
the event went out as the new anonymous user with the previous user's flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #686 release notes into the 6.0 docs

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
turnipdabeets added a commit that referenced this pull request Nov 3, 2026
#686 landed in #673 as a squash, so this merge uses #686's last head
(a339b60) as its base. Conflicts with #688: capturePrepared and
captureAiPrepared take the prepared event's distinctId, and an event
whose user changed during beforeSend leaves the new user's person state
alone, as before.
turnipdabeets and others added 5 commits November 3, 2026 15:50
* chore!: adopt posthog-ios 4.0

- Require posthog-ios 4.x.
- Adapt to the reloadFeatureFlags(_:) callback that now passes a
  PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913).
- Note the payload decoding changes from PostHog/posthog-ios#903.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changeset): note posthog-ios 4.0 drops lifecycle version and build

PostHog/posthog-ios#905 removes the legacy version/build properties from
lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener

posthog-ios 4.0 removes the didReceiveFeatureFlags notification.

* chore!: adopt posthog-android 4.0 (#663)

* chore!: adopt posthog-android 4.0

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664)

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags

onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes.

* fix: complete the web reloadFeatureFlags with the reloaded flags

Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back.

* chore: use PostHogFeatureFlagsCallback from posthog-android 4.0

* chore: fix ktlint function-signature

* fix: await posthog-js reloadFeatureFlagsAsync on web

The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js.

* docs: pass the loaded flags in the setup example

* docs: drop best-effort web note from the person and group property methods

* fix(web): wait for posthog-js flags retries before reporting a reload failure

posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed.

* docs: note where onFeatureFlags and errorsLoading differ on Android and web

* docs: describe the older posthog-js reload timeout as the full retry budget

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): fold the posthog-android 4.0 and flags-loaded entries into one changeset

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add an onFeatureFlags listener you can unsubscribe

* fix: isolate failing flag listeners, skip web registration without onFeatureFlags, update API snapshot

* fix: deliver flag loads to onFeatureFlags listeners before the config callback

A config callback that threw kept listeners from getting the load, and a
reset() or close() it started was undone when the load was cached after it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): stop flag registrations left by close() or the posthog-js loader

A registration whose unsubscribe isn't stored yet (close() during the synchronous replay) or never arrives (the loader snippet's stub) now goes inert once setup() or close() runs again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: drop native flag loads sent before a reset or close reached native

Dart bumps a generation when reset() or close() clears the listener registry and sends it with setup, reset and close. Android and iOS tag each onFeatureFlags notification with the generation they had when it fired, and Dart drops ones from an earlier generation, so the previous user's flags can't repopulate the replay cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: start receiving native flag loads when the first listener is added

With native auto-init, Posthog().onFeatureFlags() can be the app's only
Dart SDK call, and nothing created the platform that installs the channel
handler, so native loads never reached the listener.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: deliver Android reloadFeatureFlags results to onFeatureFlags listeners

posthog-android passes a manual reload only to its completion, so no
onFeatureFlagsCallback arrives and listeners missed the load while new
ones replayed the older snapshot. A reload that finishes after a reset or
close is still dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: stop passing RRStyle to replay screenshot frames (#684)

posthog-android 4.0 drops RRStyle and the wireframe tree fields from the
internal RRWireframe; screenshot frames don't need a style.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): clear replayed flags when a queued reset reaches posthog-js

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #670 release notes into the 6.0 docs

* fix: don't throw when SDK calls run before the Flutter binding exists

Posthog() creates PosthogFlutterIO, whose constructor set the channel handler
and aborted without a binding. Retry the install instead, and fail native calls
with a PlatformException so each caller's existing fallback applies.

* fix: stop delivering a flags load that a listener's reset() or close() cleared

The listeners after it and the config callback no longer get the old flags.

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* feat!: remove PostHogConfig.onFeatureFlags in favor of the listener (#695)

* feat!: remove PostHogConfig.onFeatureFlags in favor of the listener

Posthog().onFeatureFlags() can be registered before setup() and removed, so the
config field no longer adds anything. Android now drives Dart from the
posthog-android listener like iOS does, which also fires after a manual reload,
so the Dart-side Android reload delivery goes away.

* docs: fold #695 release notes into the 6.0 docs

* test: use the onFeatureFlags listener in desktop tests from the base merge

* fix(example): initialize the binding before registering the flags listener

* docs: show the removed onFeatureFlags constructor argument in the migration guide

* test: use the flags listener in the #694 desktop tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ent (#690)

* ci: run the capture v1 compliance suites against the real desktop client

The adapter posted events to /batch with its own sender, so the harness never
exercised the SDK's capture v1 code. It now captures through DesktopPostHog and
records requests with a local forwarding proxy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: read the adapter's pending events from the SDK queues

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: keep status and redirects as the SDK would see them in the adapter proxy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: bound how long the adapter proxy waits for the harness

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: fail the check when the compliance suites fail

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: let the adapter proxy wait as long as the AI client

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: run the compliance suites through the SDK's event and flag code

The adapter called captureStateless and sent its own /flags request, so
the suites skipped how the SDK builds events and evaluates flags. Events
now go through prepareEvent and capturePrepared, and flags through
reloadFeatureFlagsAsync and getFeatureFlagResult.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: keep flag state per user and count captures as they happen

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: skip the anonymous flag reload when the adapter switches users

reset() reloads flags for its rotated anonymous id before the adapter sets the requested user. That sent an extra request, and its flags were served if the user's own reload then failed.

* ci: pass non-HTTP redirects through the compliance proxy

Uri.origin throws for other schemes and hostless URLs, so the proxy answered 502 and the SDK retried a redirect it treats as terminal.

* docs: list the recording proxy test in the adapter test command

* test: expect a 2xx without readable results to be dropped in the adapter

Capture now drops such a batch for good, like posthog-ios and posthog-android. The redirect test answers with per-event results, and the truncated-body test expects a drop with no retry.

* test(compliance): declare property_layers, fail_open, generated_payloads and log_capture

The adapter now runs the configured beforeSend callbacks with the SDK's
applyBeforeSend, registers super_properties, routes /init through the
same project-token check Posthog.setup uses (extracted to
isUsableProjectToken), pads /capture_ai properties for the event-size
tests and records debugPrint lines for /state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: drive the compliance adapter through the real desktop plugin

The adapter hand-copied the plugin's capture steps, so the suites could
pass on code apps don't run. PosthogFlutterDesktop now takes an optional
test-only client factory, and the adapter captures through the plugin's
capture() and captureAi(), with the harness's distinct id and timestamp
set on the injected client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(compliance): admit the trimmed project token, as public setup does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…roid (#682)

* feat!: run beforeSend on the native-built event on iOS, macOS and Android

Dart beforeSend callbacks now get the event the native SDK built, with
its system and registered properties, uuid, distinct id and timestamp,
and the native SDK sends what they return without adding properties.
Without callbacks, events still take one native call.

Also adds PosthogFlutterPlugin.addBeforeSend in Swift and Kotlin for
events the native SDK captures itself.

* fix: import only the PostHogInternal SPI from posthog-ios

* fix: drop built events whose beforeSend callbacks never finish

* fix: clear pending built events on setup and close

* fix: keep primitive arrays when sending built events over the channel

* feat(desktop): give beforeSend the full event and add nothing after it

- On Windows and Linux, `PostHogEvent` now carries the event's uuid,
  distinct ID and timestamp, as on iOS, macOS and Android. A callback can
  change the distinct ID (a blank one keeps the current) and the
  timestamp; the event keeps its uuid.
- `$exception_steps` are attached as the event is built, before the
  callbacks, as posthog-ios and posthog-android do, so a callback sees
  and can remove them. Steps recorded while a callback runs, or an event
  renamed to `$exception`, no longer get them.
- The prepared core event carries its uuid and distinct ID, which the
  queue keeps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style: merge the repeated guards in buildEvent for swiftformat 0.64

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep another distinct id's person properties out of the current user's flag cache

When a beforeSend callback sends the event for another distinct id, its
$set and $set_once no longer update the current user's flag person
properties or person-properties hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: optOut, close and setup wait for an event being sent

Native refuses sendBuiltEvent once one of them has reached it, so the event
would be lost if they could run between buildEvent and sendBuiltEvent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(beforeSend): run the callbacks set when the event was captured

setup() replaces the callbacks synchronously, so an event still waiting on
its native build ran the next setup's chain, or none, and skipped its filter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(beforeSend): keep capture semantics for events named $screen

With callbacks set, capture('$screen') reached the native builders' screen()
path, which drops an event without a $screen_name and, on iOS, ignores person
properties. Build it under another name and restore the name in Dart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): decide person processing before beforeSend

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #682 release notes into the 6.0 docs

* fix(desktop): keep another distinct id's person properties from enabling person processing

When a beforeSend callback sends an event with person properties for another
distinct id, the current user's persisted person processing state stays off,
so their later events keep process_person_profile: false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): decide later events' person processing from what the app captured

Matches iOS and Android. A callback that adds $set to an anonymous event no
longer turns person processing on for later events, and one that strips $set
no longer leaves it off after a person-processed event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say person processing is decided before beforeSend on native

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: give beforeSend callbacks typed nested values on iOS, macOS and Android

Nested values from the method channel are untyped, so a callback casting
$exception_list to List<Map<String, dynamic>> threw and the event was dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(darwin): expire built events on a monotonic clock

A wall clock jump during a beforeSend callback could evict and lose the
event. Android already uses a monotonic clock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say what the one-minute built-event expiry covers now that callbacks are sync

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep events and user properties through beforeSend (#698)

* feat!: make beforeSend callbacks synchronous

Event and log beforeSend callbacks no longer return FutureOr, matching the
native SDKs and the before-send-hook spec. The event is handed to the SDK in
the same call, so calls made right after an un-awaited capture can no longer
reach the SDK first, on every platform including Windows and Linux.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the call queue on iOS, macOS and Android

With #682 and beforeSend set, an event takes two native calls. Without the
queue, an optOut(), close() or setup() made right after capture() reaches
native between them and the event is lost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(android): restore the screenshot scale expectation lost in the main merge

* fix(web): hand feature events to posthog-js before yielding

Without CallOrder the await on the flag lookup let a reset() made right after
an un-awaited captureFeatureView or captureFeatureInteraction overtake it, so
the event went out as the new anonymous user with the previous user's flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold #686 release notes into the 6.0 docs

* fix: run a renaming beforeSend once and keep its user properties

A hook that renamed a screen or exception ran again through capture() and lost
its userProperties on web, iOS, Android and macOS. Also covers calls made from
inside a hook and bursts of events, and documents that a hook blocks the UI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep events when beforeSend resets on desktop or sets user properties on web

On Windows and Linux, a callback calling reset() or identify() dropped the
event. It now goes out as the user it was prepared for, as on iOS, Android and
macOS. On web, userProperties set on a screen or exception that kept its name
were lost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): keep an event on its user when beforeSend changes the user

posthog-js builds the event after the callbacks, so one calling reset() or
identify() moved the event to the new user. It now stays on the earlier user,
as on the other platforms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): keep the prepared user's person and session state when beforeSend changes the user

A hook calling reset() or identify() left the event on its original user,
but person processing was recomputed from the replacement's state, and a
$screen hook calling reset() put the old screen in the new session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): don't restore the distinct id across a beforeSend consent change

Under cookieless_mode on_reject, restoring the id reattached the opted-out
user to a cookieless event, or sent the shared cookieless id after opting in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): drop user properties when beforeSend resets the user

posthog-js stores an event's $set as the current user's person properties
for flags, so after a reset() in the callback they reached the next user.
identify() of an anonymous user links the two, so they stay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: note what a web beforeSend calling reset() keeps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: add exception steps before beforeSend on Windows and Linux

beforeSend can now read, change or remove $exception_steps, as on iOS and Android.

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* fix(compliance): pass uuid and prepared-event identity through the adapter

The adapter's captureStateless/captureAiStateless overrides now forward
the uuid parameter, and its prepareEvent override copies uuid, distinctId
and requestsPersonProcessing, so it compiles against #690's base.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix: drop an event with a lone surrogate in its name or ids on Windows and Linux

Capture v1 rejects the whole request for a lone UTF-16 surrogate in a
top-level field, so one bad event lost its batch. Drop that event at
enqueue, and replace lone surrogates in properties and options with U+FFFD.

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* fix: repair lone surrogates only in queued events, and keep dropped events from changing state

register() and the flag property stores keep their values as given, so a
registered id with a lone surrogate drops later events instead of being
repaired, and unregister() still matches its key. A dropped event no longer
updates person properties, and identify() ignores an id that isn't
well-formed instead of saving it.

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* perf: repair lone surrogates in the background worker when the body is encoded

The scan cost as much as jsonEncode on the UI isolate; in the worker it
also covers property values sent as their toString().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: ignore alias() and group() calls with a lone surrogate

Repairing them would merge distinct aliases or groups into one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: note in the changeset that identify, alias and group ignore a lone surrogate

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: repair lone surrogates in event names and ids on Windows and Linux

Send the event with U+FFFD instead of dropping it, as iOS, macOS and
Android already do through the platform channel. identify(), alias()
and group() store the repaired id instead of ignoring the call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: repair lone surrogates in the /flags request on Windows and Linux

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: cover the /flags request in the lone surrogate changeset entry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep ids as given and repair lone surrogates only on the wire

identify(), alias() and group() stored a repaired id, while bootstrap,
storage and resetGroupPropertiesForFlags() kept what the app passed, so
the same id compared unequal: identify() after an identified bootstrap
was treated as a user switch, and a group type's flag properties could
not be reset. Ids now stay as the app passed them everywhere in the SDK,
and the capture and /flags bodies are repaired when they are encoded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf: copy a request body only when it has a lone surrogate

Encode first and repair only when the JSON has a \udXXX escape, so normal
batches skip the extra copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… platform (#701)

* docs: link the capture v1 SDK upgrade guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: cover capture v1 on Windows and Linux and align the 6.0 guide with the backend SDK guides

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* docs: lone surrogates on Windows and Linux (#703)

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* docs: identify ignores a distinct ID with a lone surrogate (#703)

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* docs: complete the platform interface changes and the upgrade checklist

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: document the final 6.0 state in the guide and one grouped changeset

Folds in the MIGRATION.md and changeset text of #682, #698, #703, #670,
#695 and #699 so landing this PR last is "take this side".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: describe lone surrogates as repaired on Windows and Linux

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: cover the /flags request in the lone surrogate changeset entry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: note the /flags request in the lone surrogate guide line

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say the SDK keeps lone-surrogate ids as passed and repairs what it sends

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: drop the confirmed capture v1 default TODOs from the guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say $locale follows a per-app language picked in macOS Settings too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
posthog-android 4.0 keeps the 3.x PostHogEvent constructor and copy so
posthog-server stays compatible, and makes options a property instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread .changeset/v6-major-release.md Resolved
turnipdabeets and others added 2 commits November 5, 2026 09:36
…ntity (#704)

When events wait to be retried, the next request of their lane sends
exactly those events, so it keeps PostHog-Request-Id and created_at and
increments PostHog-Attempt. Newer events go out after it as a new
request. If one of the events to retry is gone from the queue, the lane
falls back to normal batching and starts a new request at attempt 1.

Matches posthog-android 4.0 and the backend capture v1 SDKs.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
)

* chore!: adopt posthog-ios 4.0

- Require posthog-ios 4.x.
- Adapt to the reloadFeatureFlags(_:) callback that now passes a
  PostHogFeatureFlagsLoaded (PostHog/posthog-ios#913).
- Note the payload decoding changes from PostHog/posthog-ios#903.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changeset): note posthog-ios 4.0 drops lifecycle version and build

PostHog/posthog-ios#905 removes the legacy version/build properties from
lifecycle events in 4.0, so Flutter iOS and macOS apps stop sending them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(ios): drive onFeatureFlags from the posthog-ios onFeatureFlags listener

posthog-ios 4.0 removes the didReceiveFeatureFlags notification.

* chore!: adopt posthog-android 4.0 (#663)

* chore!: adopt posthog-android 4.0

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags (#664)

* chore!: pass the loaded flags to onFeatureFlags and reloadFeatureFlags

onFeatureFlags and reloadFeatureFlags now carry a PostHogFeatureFlagsLoaded with the enabled flags, their values and whether loading failed, matching posthog-ios 4.0 and posthog-android 4.0. On web, reloadFeatureFlags completes right away with the flags loaded so far, because posthog-js doesn't report when a reload finishes.

* fix: complete the web reloadFeatureFlags with the reloaded flags

Wait for the next posthog-js onFeatureFlags call instead of returning the flags already loaded, so a failed reload reports errorsLoading. Complete right away when flags are disabled, and after twice the flags request timeout when posthog-js skips the request without calling back.

* chore: use PostHogFeatureFlagsCallback from posthog-android 4.0

* chore: fix ktlint function-signature

* fix: await posthog-js reloadFeatureFlagsAsync on web

The next onFeatureFlags callback can carry a response from a request already in flight, so reloadFeatureFlags() could complete with flags from before the reload. posthog-js 1.438.2+ settles reloadFeatureFlagsAsync() after this reload's own request; use it when present and keep the callback path for older posthog-js.

* docs: pass the loaded flags in the setup example

* docs: drop best-effort web note from the person and group property methods

* fix(web): wait for posthog-js flags retries before reporting a reload failure

posthog-js retries a timed-out /flags request once by default, 500 ms later, inside the same reload. The older-JS deadline of twice the request timeout reported cached flags with errorsLoading set before a successful retry landed.

* docs: note where onFeatureFlags and errorsLoading differ on Android and web

* docs: describe the older posthog-js reload timeout as the full retry budget

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): fold the posthog-android 4.0 and flags-loaded entries into one changeset

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add an onFeatureFlags listener you can unsubscribe

* fix: isolate failing flag listeners, skip web registration without onFeatureFlags, update API snapshot

* fix: deliver flag loads to onFeatureFlags listeners before the config callback

A config callback that threw kept listeners from getting the load, and a
reset() or close() it started was undone when the load was cached after it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): stop flag registrations left by close() or the posthog-js loader

A registration whose unsubscribe isn't stored yet (close() during the synchronous replay) or never arrives (the loader snippet's stub) now goes inert once setup() or close() runs again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: drop native flag loads sent before a reset or close reached native

Dart bumps a generation when reset() or close() clears the listener registry and sends it with setup, reset and close. Android and iOS tag each onFeatureFlags notification with the generation they had when it fired, and Dart drops ones from an earlier generation, so the previous user's flags can't repopulate the replay cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: start receiving native flag loads when the first listener is added

With native auto-init, Posthog().onFeatureFlags() can be the app's only
Dart SDK call, and nothing created the platform that installs the channel
handler, so native loads never reached the listener.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: deliver Android reloadFeatureFlags results to onFeatureFlags listeners

posthog-android passes a manual reload only to its completion, so no
onFeatureFlagsCallback arrives and listeners missed the load while new
ones replayed the older snapshot. A reload that finishes after a reset or
close is still dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: stop passing RRStyle to replay screenshot frames (#684)

posthog-android 4.0 drops RRStyle and the wireframe tree fields from the
internal RRWireframe; screenshot frames don't need a style.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* fix(web): clear replayed flags when a queued reset reaches posthog-js

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat!: remove PostHogConfig.onFeatureFlags in favor of the listener

Posthog().onFeatureFlags() can be registered before setup() and removed, so the
config field no longer adds anything. Android now drives Dart from the
posthog-android listener like iOS does, which also fires after a manual reload,
so the Dart-side Android reload delivery goes away.

* docs: fold #670 release notes into the 6.0 docs

* docs: fold #695 release notes into the 6.0 docs

* test: use the onFeatureFlags listener in desktop tests from the base merge

* fix(example): initialize the binding before registering the flags listener

* fix: don't throw when SDK calls run before the Flutter binding exists

Posthog() creates PosthogFlutterIO, whose constructor set the channel handler
and aborted without a binding. Retry the install instead, and fail native calls
with a PlatformException so each caller's existing fallback applies.

* docs: show the removed onFeatureFlags constructor argument in the migration guide

* feat!: report the device language as $locale and add $app_language

* fix: address the pre-PR review of $locale and $app_language

* docs: correct the $locale migration notes

* fix: forward setAppLanguage on web

* test: use the flags listener in the #694 desktop tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: stop delivering a flags load that a listener's reset() or close() cleared

The listeners after it and the config callback no longer get the old flags.

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

* fix: keep $app_language on a web capture made right after reset()

posthog-js clears registered properties on reset, and the language was only
registered again after an await, so an un-awaited capture() went out without
it. The web plugin now registers it in the same step as the reset. Native and
desktop keep the language across reset, so Posthog.reset() no longer resends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say $locale follows a per-app language on iOS and macOS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: drop the duplicate $locale upgrade checklist item

#701 already lists it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@turnipdabeets
turnipdabeets merged commit cd51a5c into chore/v6-posthog-ios-4 Nov 5, 2026
8 checks passed
@turnipdabeets
turnipdabeets deleted the feat/v6-desktop-capture-v1 branch November 5, 2026 14:37
gewenyu99 added a commit that referenced this pull request Nov 11, 2026
)

* docs: generate the Flutter SDK reference for 5.x

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: generate the Flutter SDK reference for the 6.x experimental major

Generated from feat/v6-desktop-capture-v1 (#637 and #673) with the capability tags applied.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: regenerate the Flutter references from dart doc

The 6.x page comes from chore/v6-posthog-ios-4 (the 6.0 branch) with the
capability tags and getting-started applied. Both still need to land there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Flutter references with code braces and clean signatures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Flutter 6.x reference with Capture AI and On feature flags

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add the Flutter 5.x to 6.0 migration page

Built from posthog_flutter/MIGRATION.md on chore/v6-posthog-ios-4 (#637),
the way the generator builds it once that guide is on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Flutter migration page from the current 6.0 guide

Rebuilt from posthog_flutter/MIGRATION.md on chore/v6-posthog-ios-4, which now
notes the beforeSend option loss on native and the new flag and event fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Flutter references

Member headings show their names again, and the 6.x and migration pages are
rebuilt from the current chore/v6-posthog-ios-4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the references with the getting-started intro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants