docs: correct push-notification open coverage for iOS, Android and Flutter

[turnipdabeets]

Changes

Corrects the push-notification open-tracking docs for iOS, Android and Flutter. Some of this is wrong today, independent of any SDK change.

iOS never captures a tap unless the app sets a UNUserNotificationCenter delegate. The page currently says the SDK "picks up the token and open events automatically". The token half is true; the open half is not — PostHog swizzles the app's delegate rather than installing its own, so with no delegate iOS reports the tap to nobody and $push_notification_opened is never captured, in any app state. This is the most likely reason a reader sees zero events, and it's what PostHog/posthog-flutter#555 turned out to be. Neither a stock Flutter app nor flutter_local_notifications sets one.

The Flutter page tells users to capture Android warm taps themselves. Once PostHog/posthog-flutter#557 ships, the plugin captures that tap too, and the manual API isn't deduplicated against it — so anyone following the current snippet double-counts every warm tap. Replaced with an example that can't collide, plus an explicit "don't wire this to onMessageOpenedApp / getInitialMessage()".

The Android page points at the manual API for warm taps. PostHog/posthog-android#753 adds PostHogAndroid.capturePushNotificationOpened(intent), which dedupes against the automatic path. Also documents the singleTop requirement — without it the system resumes the task instead of delivering the tap, so the snippet would never fire — and that detection is FCM-specific (google.message_id).

React Native carries the same iOS overclaim, so that one sentence is corrected. The RN cold-start gap itself is not fixed and is out of scope here.

Related

PostHog/posthog-ios#792	prewarmPushNotificationOpenCapture(), and the missing-delegate warning
PostHog/posthog-android#753	PostHogAndroid.capturePushNotificationOpened(intent)
PostHog/posthog-flutter#556	iOS cold-start capture — PostHog/posthog-flutter#555
PostHog/posthog-flutter#557	Android cold and warm start — PostHog/posthog-flutter#558

Timing

Draft. The two behavioural statements — Android warm-start capture being automatic, and cold start working at all — only become true when the SDK releases land. The delegate and FCM-detection corrections are true today and could merge sooner if you'd rather split them.

The Flutter SDK version numbers are deliberately not stated: #556 and #557 ship separately with different native gates, so which release carries which half depends on merge order. Native floors (posthog-ios 3.72.0, posthog-android 3.62.0) are certain and are stated.

Testing

The behaviour described here was verified on device — iPhone 17 Pro simulator and a Pixel 9 emulator — for cold and warm starts on both platforms, in native and Flutter hosts, with events confirmed in a real PostHog project. Details in the linked SDK PRs.

Not verified: the site hasn't been built locally, so the CalloutBox rendering is unchecked.

🤖 Generated with Claude Code

https://claude.ai/code/session_012txiHBCZRkShMdE7V25Jrd

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Sep 02, 2026 04:19PM

[github-actions]

Vale prose linter → found 8 errors, 37 warnings, 11 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/workflows/push-notifications/android.mdx — 2 errors, 6 warnings, 2 suggestions

Line	Severity	Message	Rule
12:94	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
16:72	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
48:37	warning	'unregisters' is a possible misspelling.	PostHogBase.Spelling
48:127	warning	Use 'ID' instead of 'id'.	Vale.Terms
50:18	warning	'unregistration' is a possible misspelling.	PostHogBase.Spelling
65:270	warning	Use 'ID' instead of 'id'.	Vale.Terms
65:307	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
67:123	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
94:66	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
95:102	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress

contents/docs/workflows/push-notifications/flutter.mdx — 4 errors, 12 warnings, 3 suggestions

Line	Severity	Message	Rule
12:118	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
26:110	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
26:254	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
26:334	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
28:185	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
30:26	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
30:34	warning	Use 'iOS' instead of 'ios'.	Vale.Terms
30:56	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
30:64	warning	Use 'Android' instead of 'android'.	Vale.Terms
34:192	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
50:9	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	PostHogBase.ProductNames
76:1	warning	'Unregister' is a possible misspelling.	PostHogBase.Spelling
84:18	warning	'unregistration' is a possible misspelling.	PostHogBase.Spelling
88:115	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
125:66	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
125:159	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
126:77	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
126:105	warning	Use 'ID' instead of 'id'.	Vale.Terms
127:189	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

contents/docs/workflows/push-notifications/ios.mdx — 1 errors, 10 warnings, 3 suggestions

Line	Severity	Message	Rule
12:192	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
13:28	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
13:79	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
13:98	warning	Use 'ID' instead of 'id'.	Vale.Terms
27:199	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
31:243	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
47:9	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	PostHogBase.ProductNames
69:1	warning	'Unregister' is a possible misspelling.	PostHogBase.Spelling
75:52	warning	'unregisters' is a possible misspelling.	PostHogBase.Spelling
75:142	warning	Use 'ID' instead of 'id'.	Vale.Terms
77:18	warning	'unregistration' is a possible misspelling.	PostHogBase.Spelling
115:83	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
116:47	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
116:120	warning	Use 'ID' instead of 'id'.	Vale.Terms

contents/docs/workflows/push-notifications/react-native.mdx — 1 errors, 9 warnings, 3 suggestions

Line	Severity	Message	Rule
12:132	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
32:110	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
32:252	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
32:382	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
34:184	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
59:54	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
59:83	warning	Use 'ID' instead of 'id'.	Vale.Terms
61:1	warning	'Unregister' is a possible misspelling.	PostHogBase.Spelling
69:18	warning	'unregistration' is a possible misspelling.	PostHogBase.Spelling
123:112	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
123:203	warning	'classpath' is a possible misspelling.	PostHogBase.Spelling
124:77	warning	'APNs' is a possible misspelling.	PostHogBase.Spelling
124:105	warning	Use 'ID' instead of 'id'.	Vale.Terms

[github-actions]

Bundle report

Total JS (gzip)

8.15 MiB (no change)

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

Entrypoint	Eager size	Budget	Modules
✅ app	18.37 MiB (+0.6 KiB / +0.0%)	report-only	2049

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1070.3 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	758.3 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js	481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs	480.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.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs	385.7 KiB
./src/hooks/useCustomers.tsx + 55 modules	370.0 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 + 126 modules	301.7 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs	281.7 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs	275.6 KiB
./src/components/SearchUI/index.tsx + 87 modules	273.0 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).