docs(flutter): version 6 upgrade guide by turnipdabeets · Pull Request #20924 · PostHog/posthog.com

turnipdabeets · 2026-10-07T20:42:40Z

Changes

CocoaPods is removed in 6.0. Swift Package Manager becomes the only iOS and macOS option, with Flutter 3.41 or later, and add-to-app modules stay on 5.x. The install snippets, surveys page, tutorials and upgrade section all say so. This also depends on PostHog/posthog-flutter removing posthog_flutter.podspec, which no branch has done yet.

Migration file: the upgrade section links posthog_flutter/MIGRATION.md in posthog-flutter.

Docs for posthog_flutter 6.0. Hold until 6.0 is released. It depends on PostHog/posthog-flutter#637, #649, #663, #673, #682 and #686 (#682 and #686 are still open, and the beforeSend text below is only true with them), which wait on the posthog-ios 4.0 release (PostHog/posthog-ios#873, PostHog/posthog-ios#938) and the posthog-android 4.0 release (PostHog/posthog-android#871, PostHog/posthog-android#881). Several of these pages describe 6.0 requirements (iOS 15, Xcode 26, PROJECT_TOKEN only), which are wrong for 5.x users until then.

New "Upgrading from version 5 to version 6" section at the end of /docs/libraries/flutter. It covers:
- Platform requirements: iOS 15, macOS 11 and Xcode 26. Android stays at API 23.
- A table of each removed API and what to use instead.
- A before/after example for reading a flag payload.
- Notes for custom platform implementations and test mocks.
- Capture v1: on iOS, macOS, Android, Windows and Linux, events go to /i/v1/analytics/events and AI events to /i/v1/ai/events. Web stays on posthog-js and its current endpoints. The section lists the routes, headers and body size that a reverse proxy must forward, and tells users that one proxy for all platforms needs both sets of routes.
- Property precedence: registered and passed properties now win over SDK properties. beforeSend sees all properties on every platform except web (Fixed link to "Spending money" section of the handbook. #682).
- PostHogConfig.onFeatureFlags is removed in favor of Posthog().onFeatureFlags((loaded) { ... }) before setup(), and reloadFeatureFlags() returns a PostHogFeatureFlagsLoaded.
- Synchronous beforeSend (Fix Superlist of Minor Issues #686).
- What changed from 5.x on Windows and Linux: backoff, timeout, redirects, Retry-After, batch size, non-finite numbers, empty names and logs.
- The new per-event options argument and captureAi, with the web limits.
- Retries: 404 and 429 are retried, 1–30 s backoff with jitter, Retry-After capped at 30 s.
- Three iOS/macOS behavior changes that come from posthog-ios 4.0: malformed payloads become null, bootstrapped string payloads stay strings, and lifecycle events no longer include version/build.
beforeSend limitations now say the callbacks get the final event (Fixed link to "Spending money" section of the handbook. #682).
New Event options and Capturing AI events reference sections, and AI observability is marked as supported.
Opt-out section now uses optOut()/optIn(). Both shipped in 5.51.0; disable()/enable() are removed in 6.0.
Install snippets and the Flutter surveys page: the minimum is now iOS 15.0 instead of 13.0, with a note that building requires Xcode 26.
Flutter tutorials (analytics, A/B tests, feature flags, remote config):
- com.posthog.posthog.API_KEY → PROJECT_TOKEN. 6.0 no longer reads API_KEY, while PROJECT_TOKEN already works on 5.x.
- minSdkVersion 21 → 23. posthog-android already requires 23.
- iOS 13 → 15.
Feature flags snippet (feature-flags-code-flutter.mdx, shown on /docs/libraries/flutter and /docs/feature-flags/adding-feature-flag-code): uses Posthog().onFeatureFlags((loaded) { ... }) before setup(), with a note for 5.x readers to keep config.onFeatureFlags.
Cost-cutting page: the Flutter sample now uses sendFeatureFlagEvent instead of sendFeatureFlagEvents, which 6.0 removes.

Every claim was checked against the 6.0 branches and posthog-ios 4.0. Vale reports no alerts on the changed lines, apart from "Podfile" flagged as a misspelling on lines that already used the word.

Not in this PR:

The in-app onboarding steps in the posthog monorepo (docs/onboarding/product-analytics/flutter.tsx and docs/onboarding/session-replay/flutter.tsx) still say iOS 13. They need a separate PR at release.
session-replay/_snippets/flutter-installation.mdx and surveys/_snippets/flutter-surveys-installation.mdx also say iOS 13, but nothing imports them, so I left them unchanged.

Checklist

I've read the docs and/or content style guides.
Words are spelled using American English
Use relative URLs for internal links
I've checked the pages added or changed in the Vercel preview build
If I moved a page, I added a redirect in vercel.json

🤖 Generated with Claude Code

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

github-actions · 2026-10-07T20:43:13Z

Deploy preview

Status	Details	Updated (UTC)
🔴 Failed	View logs	Nov 03, 2026 04:31PM

Push a fix or re-run the workflow to try again.

Common culprits

MDX issues - unescaped </> characters, unclosed tags, or malformed JSX
External API timeouts - GitHub, Strapi, or Ashby occasionally hiccup

github-actions · 2026-10-07T20:43:40Z

Vale prose linter → found 5 errors, 88 warnings, 5 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/feature-flags/cutting-costs.mdx — 0 errors, 23 warnings, 0 suggestions

Line	Severity	Message	Rule
21:1	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	`PostHogBase.ProductNames`
21:102	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
23:30	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
26:63	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
37:1	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	`PostHogBase.ProductNames`
61:127	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
65:118	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
67:96	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
69:99	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
69:195	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
69:240	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
69:275	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
75:17	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
75:95	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
75:115	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
92:36	warning	'ETags' is a possible misspelling.	`PostHogBase.Spelling`
92:151	warning	Use 'PostHog' instead of 'posthog'.	`Vale.Terms`
104:107	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
256:214	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
256:229	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	`PostHogBase.ProductNames`
256:249	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
272:42	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
272:69	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`

contents/docs/integrate/_snippets/install-flutter.mdx — 0 errors, 1 warnings, 0 suggestions

Line	Severity	Message	Rule
130:6	warning	'Dart setup (For manual step only)' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`

contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-flutter.mdx — 0 errors, 7 warnings, 0 suggestions

Line	Severity	Message	Rule
1:13	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
13:18	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
27:83	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
29:39	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
49:91	warning	Use 'X' instead of 'x'.	`Vale.Terms`
51:15	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
53:91	warning	'refetch' is a possible misspelling.	`PostHogBase.Spelling`

contents/docs/libraries/flutter/index.mdx — 5 errors, 43 warnings, 5 suggestions

Line	Severity	Message	Rule
6:18	warning	Use 'GitHub' instead of 'github'.	`Vale.Terms`
6:37	warning	Use 'PostHog' instead of 'posthog'.	`Vale.Terms`
90:72	warning	'cookieless' is a possible misspelling.	`PostHogBase.Spelling`
198:49	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	`PostHogDocs.DirectAddress`
200:66	suggestion	Address the reader directly. Use 'you' instead of 'the User'.	`PostHogDocs.DirectAddress`
200:131	suggestion	Address the reader directly. Use 'you' instead of 'the User'.	`PostHogDocs.DirectAddress`
214:69	warning	Avoid trivializing words. 'simply' can sound dismissive to the reader.	`PostHogDocs.Trivializers`
222:4	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	`PostHogBase.ProductNames`
222:4	warning	'Feature flags' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`
235:79	warning	Use 'X' instead of 'x'.	`Vale.Terms`
276:25	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
280:8	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	`PostHogBase.ProductNames`
280:55	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
280:128	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
282:28	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	`PostHogBase.ProductNames`
282:54	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
284:4	warning	'Error tracking' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`
284:4	warning	Capitalize 'Error Tracking' for PostHog's product. Use 'Error tracking' for the general industry concept.	`PostHogBase.ProductNames`
286:11	warning	Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept.	`PostHogBase.ProductNames`
286:52	warning	Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept.	`PostHogBase.ProductNames`
290:12	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
292:4	warning	'Session replay' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`
292:4	warning	Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept.	`PostHogBase.ProductNames`
294:13	warning	Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept.	`PostHogBase.ProductNames`
296:12	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	`PostHogBase.ProductNames`
296:65	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	`PostHogBase.ProductNames`
296:127	warning	Avoid trivializing words. 'all you need to do' can sound dismissive to the reader.	`PostHogDocs.Trivializers`
301:111	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	`PostHogBase.EnDash`
301:276	warning	Use 'PostHog' instead of 'posthog'.	`Vale.Terms`
355:96	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	`PostHogDocs.DirectAddress`
356:8	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	`PostHogDocs.DirectAddress`
435:24	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	`PostHogBase.EnDash`
436:26	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	`PostHogBase.EnDash`
437:23	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	`PostHogBase.EnDash`
438:33	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	`PostHogBase.EnDash`
442:3	warning	Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept.	`PostHogBase.ProductNames`
469:62	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
469:100	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
480:26	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
530:5	warning	'Move from CocoaPods to Swift Package Manager' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`
532:18	warning	'podspec' is a possible misspelling.	`PostHogBase.Spelling`
547:173	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
583:117	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	`PostHogBase.ProductNames`
623:84	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	`PostHogBase.ProductNames`
630:1	warning	Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept.	`PostHogBase.ProductNames`
630:9	warning	Use the Oxford comma before 'and' or 'or' in a list of three or more items.	`PostHogBase.OxfordComma`
630:17	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
630:26	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
630:51	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	`PostHogBase.ProductNames`
632:38	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	`PostHogBase.ProductNames`
663:230	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	`PostHogBase.ProductNames`
724:13	warning	'reachability' is a possible misspelling.	`PostHogBase.Spelling`
725:167	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`

contents/docs/surveys/installation/flutter.mdx — 0 errors, 2 warnings, 0 suggestions

Line	Severity	Message	Rule
13:64	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`
21:11	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	`PostHogBase.ProductNames`

contents/tutorials/flutter-ab-tests.md — 0 errors, 1 warnings, 0 suggestions

Line	Severity	Message	Rule
334:18	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`

contents/tutorials/flutter-analytics.md — 0 errors, 6 warnings, 0 suggestions

Line	Severity	Message	Rule
19:2	warning	Capitalize 'Product Analytics' for PostHog's product. Use 'Product analytics' for the general industry concept.	`PostHogBase.ProductNames`
322:138	warning	Use 'PostHog' instead of 'Posthog'.	`Vale.Terms`
407:23	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
448:18	warning	Capitalize 'Product Analytics' for PostHog's product. Use 'Product analytics' for the general industry concept.	`PostHogBase.ProductNames`
456:150	warning	'enabed' is a possible misspelling.	`PostHogBase.Spelling`
470:18	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`

contents/tutorials/flutter-feature-flags.md — 0 errors, 3 warnings, 0 suggestions

Line	Severity	Message	Rule
2:22	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
16:2	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	`PostHogBase.ProductNames`
200:44	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`

contents/tutorials/flutter-remote-config.md — 0 errors, 2 warnings, 0 suggestions

Line	Severity	Message	Rule
166:15	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
322:4	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	`PostHogBase.ProductNames`

github-actions · 2026-10-07T20:55:32Z

Bundle report

Total JS (gzip)

10.38 MiB (+0.6 KiB / +0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ `app`	20.90 MiB (+3.6 KiB / +0.0%)	report-only	2119

Largest modules in the app closure

Module	Size
`./src/data/mcp-tools.json`	1472.7 KiB
`css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css`	839.4 KiB
`./src/components/Stickers/Stickers.tsx`	696.4 KiB
`./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs`	481.2 KiB
`./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs`	450.8 KiB
`./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules`	395.1 KiB
`./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs`	385.8 KiB
`./src/hooks/useCustomers.tsx + 61 modules`	381.8 KiB
`./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/tourist.mjs`	364.6 KiB
`./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js`	354.8 KiB
`./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules`	351.4 KiB
`./src/components/ProductComparisonTable/index.tsx + 130 modules`	314.3 KiB
`./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules`	287.2 KiB
`./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs`	284.1 KiB
`./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js`	281.9 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

github-actions · 2026-10-22T07:44:43Z

This PR hasn't seen activity in two weeks! Should it be merged, closed, or further worked on? If you want to keep it open, please remove the stale label – otherwise this will be closed in another week. If you want to permanently keep it open, use the waiting label.

eli-r-ph · 2026-10-26T22:22:47Z

Flutter 6 sends events from iOS, macOS, Android, Windows and Linux to capture v1. Could the upgrade guide say so in one section, list what a reverse proxy must forward (/i/v1/analytics/events, /i/v1/ai/events and the Authorization header), and link the posthog-ios and posthog-android 4.0 migration guides?

eli-r-ph · 2026-10-27T02:05:26Z

One addition for the proxy section: the proxy also needs to pass every PostHog-* header through and accept request bodies up to 20 MB (nginx and ingress-nginx default to 1 MB). The server SDK guides use this checklist: https://github.com/PostHog/posthog-python/blob/235047e220c48e1a69ab7354564ceefe035c4b34/docs/migration-7.x-to-8.0.md#L44-L50

… 6 guide

turnipdabeets · 2026-10-28T23:22:37Z

@eli-r-ph I added the capture v1 parts to the Flutter 6 upgrade guide (3284e0f): endpoints per platform (web stays on posthog-js), reverse proxy and self-hosted requirements, property precedence, per-event options, captureAi, and the 404/429 retry behavior. Can you check that it matches the v1 rules for the other SDKs?

posthog

PostHog Review · Standard · reviewed 3284e0f: 5 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

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.

…, native addBeforeSend, phx_ keys everywhere

eli-r-ph · 2026-10-30T15:59:12Z

@turnipdabeets thanks, the capture v1 parts read well. A few additions for the 6.0 guide:

onFeatureFlags now takes a PostHogFeatureFlagsLoaded, and reloadFeatureFlags() returns Future<PostHogFeatureFlagsLoaded>, so 5.x callbacks written as () {} break.
AI queue defaults (100 events, 50 MiB on desktop, 60 s timeout, 8 MiB + 64 KiB event cap), and that flush() and close() also send the AI queue.
NaN and infinite property values are dropped rather than sent as null, and empty event names are dropped on the device.
What changed from 5.x on Windows and Linux: backoff with jitter instead of a fixed 3 s wait, a timeout after 10 s without progress, redirects drop the batch, Retry-After is capped at 30 s, and batches are capped at 5 MiB.
Failure reporting and logs: the loss summary is debug-only, the one-time 404 warning prints without debug, and the old log text is gone.
Synchronous beforeSend (Fix Superlist of Minor Issues #686), including that on iOS, macOS and Android a capture() followed straight away by optOut(), close() or setup() drops that event.
The proxy rule from the updated proxy guides: a proxy that strips other credentials should keep Authorization values that start with Bearer phc_, or the exact Bearer <token> if the project token doesn't start with phc_. The "managed reverse proxy" link also points to the proxy index rather than the managed proxy page.

Add Event options and Capturing AI events sections to the Flutter page, with the captureAi queue settings and their defaults. The version 6 upgrade guide now covers what changed and links to them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Add onFeatureFlags, synchronous beforeSend, the Windows and Linux changes from 5.x and the proxy Authorization rule. Link the managed proxy page, list Windows and Linux as supported, and mark AI observability as supported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

turnipdabeets · 2026-10-30T16:34:49Z

@eli-r-ph thanks, these are in now (00c3ba4, plus 0294168 for the AI queue defaults):

onFeatureFlags and reloadFeatureFlags(): added, with a before/after example.
AI queue defaults and flush()/close(): in the new "Capturing AI events" section. The 50 MiB cap applies on every platform, not just desktop, so the guide doesn't scope it to desktop.
NaN, infinite values and empty names: under Windows and Linux, since that's the Dart code I checked. In a list, a non-finite value becomes null so the other elements keep their positions.
Windows and Linux changes from 5.x: added as their own section.
Logs: the count of dropped events is debug-only and the 404 warning prints without debug. I left out "the old log text is gone", because most of the old messages, such as Error while flushing PostHog, are still in Custom icon for changelog / update notes in the new top navigation. #673. Tell me if you meant specific ones.
Synchronous beforeSend: added. The dropped event after optOut(), close() or setup() is described as happening only when beforeSend is set, because without callbacks Fixed link to "Spending money" section of the handbook. #682 still makes a single native call. Fix Superlist of Minor Issues #686's changeset still says the opposite, and your threads on Fixed link to "Spending money" section of the handbook. #682 and Fix Superlist of Minor Issues #686 are still open.
Proxy: added the Bearer phc_ rule, and the managed proxy link now goes to the managed proxy page.

The guide's beforeSend text depends on #682 and #686, so both are now listed as dependencies in the description.

posthog-flutter keeps the call queue on iOS, macOS and Android, so the event isn't dropped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

turnipdabeets · 2026-10-30T16:45:19Z

@eli-r-ph a correction to my last comment: the event is no longer dropped after optOut(), close() or setup(). iOS, macOS and Android keep CallOrder (posthog-flutter 41ea6b0), so those calls wait until the event is sent, and the guide no longer describes a drop (130b83d).

eli-r-ph · 2026-10-30T18:53:30Z

+
+In version 5, the SDK's own values won over the properties you registered or passed. In version 6, your value wins for that event. A registered `$session_id` now overrides the SDK's session ID, which can detach events from their session replay.
+
+`beforeSend` runs after the merge, so it sees and can change every property and option the SDK adds. In version 5, on iOS, macOS and Android, it ran before the native SDK added its properties and saw only the properties you passed.


Can the guide ask users to review their beforeSend hooks for the new event shape? In 3.x (Flutter 5.x) the SDK marked person processing with the $process_person_profile property; now it's the process_person_profile option. A hook that returns a new event without copying its options turns person processing on for anonymous users, which overrides personProfiles.

Fixed in bd2ef7e — added the beforeSend review note, with options: event.options to keep the option.

eli-r-ph · 2026-10-30T18:53:30Z

+
+- Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog.
+- Pass `Authorization` (the project token, sent as `Bearer <token>`), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged.
+- If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`. If your project token doesn't start with `phc_`, keep the exact value `Bearer <your project token>`.


Heads-up: we plan to widen the proxy rule in posthog.com #21792 (in review). Proxies would keep Authorization values that start with Bearer phc_, Bearer phs_ or Bearer phx_, plus the exact Bearer <key> of an older key without a prefix. Server SDKs send phs_ and phx_ keys through the same proxy for local evaluation and remote config, so a shared proxy that keeps only phc_ breaks them. Once #21792 merges, can we update this line to match the proxy guides? This SDK only sends the project token, so its own requests work either way.

Fixed in f7266bb — now matches #21792: phc_, phs_, phx_, plus the exact Bearer <key> of older keys.

eli-r-ph · 2026-11-01T21:04:50Z

+
+### Feature flag callbacks
+
+`PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed, and `reloadFeatureFlags()` returns a `Future<PostHogFeatureFlagsLoaded>`. Callbacks written as `() { ... }` no longer compile:


Flutter 6 removes PostHogConfig.onFeatureFlags (posthog-flutter #695), so this example no longer compiles. Could it show Posthog().onFeatureFlags((loaded) { ... }) called before setup(), which also covers the first load?

Fixed in b69e152 — shows Posthog().onFeatureFlags((loaded) { ... }) before setup(), and lists the removal.

eli-r-ph · 2026-11-01T21:04:51Z

+
+### Events go to capture v1
+
+On iOS, macOS, Android, Windows and Linux, version 6 sends events to capture v1 instead of `/batch/`. iOS and macOS do this through `posthog-ios` 4.0, Android through `posthog-android` 4.0, and Windows and Linux in the SDK's Dart client.


Could this section link the posthog-ios and posthog-android 4.0 migration guides, and add two rules? A 402 (over your billing limit) drops the whole request. A $session_id or $window_id that isn't a string is removed before sending.

Fixed in 1dc5fd1 — linked both native 4.0 guides and added the 402 and non-string session/window ID rules.

… shape

… rules

…nippet

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

docs(flutter): add the version 6 upgrade guide and update pages for 6.0

6df2d53

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

turnipdabeets mentioned this pull request Oct 7, 2026

chore!: Flutter Major Release v6 PostHog/posthog-flutter#637

Draft

5 of 6 tasks

github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Oct 7, 2026

turnipdabeets mentioned this pull request Oct 7, 2026

chore!: iOS Major Release 4.0 PostHog/posthog-ios#873

Draft

9 of 16 tasks

github-actions Bot added the stale This pull request has been marked as stale and will be closed soon automatically label Oct 22, 2026

turnipdabeets removed the stale This pull request has been marked as stale and will be closed soon automatically label Oct 22, 2026

turnipdabeets mentioned this pull request Oct 26, 2026

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

Open

6 of 8 tasks

docs(flutter): cover capture v1, options and captureAi in the version…

3284e0f

… 6 guide

turnipdabeets requested a review from eli-r-ph October 28, 2026 23:22

posthog Bot reviewed Oct 28, 2026

View reviewed changes

turnipdabeets added 2 commits October 28, 2026 20:50

docs(flutter): pin tutorials to posthog_flutter 6 for PROJECT_TOKEN keys

6a93390

docs(flutter): beforeSend gets the final event on every platform in 6…

b946703

…, native addBeforeSend, phx_ keys everywhere

turnipdabeets mentioned this pull request Oct 29, 2026

feat!: make beforeSend callbacks synchronous PostHog/posthog-flutter#686

Merged

5 of 6 tasks

turnipdabeets and others added 2 commits October 30, 2026 12:05

docs(flutter): optOut after capture no longer applies to the event first

130b83d

posthog-flutter keeps the call queue on iOS, macOS and Android, so the event isn't dropped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

eli-r-ph reviewed Oct 30, 2026

View reviewed changes

docs(flutter): align the version 6 upgrade guide with the migration file

b93249c

turnipdabeets mentioned this pull request Oct 31, 2026

docs(android): 3.x to 4.0 upgrade guide #21808

Draft

4 of 5 tasks

docs(flutter): version 6 installs through Swift Package Manager only

b31dabd

eli-r-ph reviewed Nov 1, 2026

View reviewed changes

turnipdabeets and others added 6 commits November 2, 2026 20:59

docs(flutter): version 6 removes PostHogConfig.onFeatureFlags

b69e152

docs(flutter): ask users to review beforeSend hooks for the new event…

bd2ef7e

… shape

docs(flutter): match the proxy guides' Authorization rule

f7266bb

docs(flutter): link the native 4.0 guides, add the 402 and session ID…

1dc5fd1

… rules

docs(flutter): use the onFeatureFlags listener in the feature flags s…

fe27989

…nippet

docs(flutter): warn about slow, late-changing and self-capturing befo…

c781eae

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


		In version 5, the SDK's own values won over the properties you registered or passed. In version 6, your value wins for that event. A registered `$session_id` now overrides the SDK's session ID, which can detach events from their session replay.

		`beforeSend` runs after the merge, so it sees and can change every property and option the SDK adds. In version 5, on iOS, macOS and Android, it ran before the native SDK added its properties and saw only the properties you passed.


		### Feature flag callbacks

		`PostHogConfig.onFeatureFlags` now receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and whether loading failed, and `reloadFeatureFlags()` returns a `Future<PostHogFeatureFlagsLoaded>`. Callbacks written as `() { ... }` no longer compile:


		### Events go to capture v1

		On iOS, macOS, Android, Windows and Linux, version 6 sends events to capture v1 instead of `/batch/`. iOS and macOS do this through `posthog-ios` 4.0, Android through `posthog-android` 4.0, and Windows and Linux in the SDK's Dart client.

Conversation

turnipdabeets commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Checklist

Uh oh!

github-actions Bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Uh oh!

github-actions Bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle report

Total JS (gzip)

Eager graph (modules shipped in each entrypoint's initial chunks)

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

eli-r-ph commented Oct 26, 2026

Uh oh!

eli-r-ph commented Oct 27, 2026

Uh oh!

turnipdabeets commented Oct 28, 2026

Uh oh!

posthog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eli-r-ph commented Oct 30, 2026

Uh oh!

turnipdabeets commented Oct 30, 2026

Uh oh!

turnipdabeets commented Oct 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

turnipdabeets commented Oct 7, 2026 •

edited

Loading

github-actions Bot commented Oct 7, 2026 •

edited

Loading

github-actions Bot commented Oct 7, 2026 •

edited

Loading

github-actions Bot commented Oct 7, 2026 •

edited

Loading