Skip to content

docs(kmp): update for posthog-kmp 0.12 - #22013

Draft
turnipdabeets wants to merge 18 commits into
masterfrom
docs/kmp-0-11
Draft

turnipdabeets wants to merge 18 commits into
masterfrom
docs/kmp-0-11

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Important

Don't merge until posthog-kmp 0.12.0 is released. It documents PostHog/posthog-kmp#108, which now carries PostHog/posthog-kmp#109, PostHog/posthog-kmp#113, PostHog/posthog-kmp#115 and PostHog/posthog-kmp#119 (all merged into it) and waits on posthog-android 4.0 and posthog-ios 4.0. Merge together with the KMP part of PostHog/posthog#125537 (replay onboarding).

Changes

Updates the Kotlin Multiplatform page for posthog-kmp 0.12:

  • Session replay: removes the screenshot option and the wireframe/screenshot-mode section. Replay always records masked screenshots now, so there's a note on masking custom-drawn content.
  • Session recording options: removes screenshot, and replaces debouncerDelayMs with throttleDelayMs (Android and iOS).
  • Build requirements: Xcode 26 or later, and macOS 11 or later for macOS targets.
  • Configure the SDK: a phx_ personal API key disables the SDK. Events go to /i/v1/analytics/events, which reverse proxies and self-hosted instances must forward.
  • New "Upgrade to 0.12.0" checklist: endpoint, token, register values that replace SDK properties, build requirements, replay and throttleDelayMs.
  • Platform support: adds the missing macOS (Apple silicon) row.
  • Event options (posthog-kmp#119): a new section for CaptureOptions.eventOptions, the eventOptions parameter, PostHogEventOptions, registerOptions()/unregisterOptions(), and PostHogEvent.options in beforeSend, with the web mapping.
  • AI events (posthog-kmp#119): a new captureAi section modeled on the Android one from docs: document captureAi for iOS, Android and Flutter #21963, and the four captureAi* config rows.
  • Feature flags: the reloadFeatureFlags callback's PostHogFeatureFlagsLoaded, onFeatureFlags(), setting person and group properties for flag evaluation, evaluationContexts, and the payload and empty-variant behavior.
  • Setting the app language: $app_language, setAppLanguage() and $locale (posthog-kmp#115).
  • Config table: adds the existing capturePushNotificationSubscriptions and capturePushNotificationOpened rows (posthog-kmp#101).
  • Upgrade checklist also covers person processing through event options, a registered $process_person_profile (which no longer applies to identify(), alias(), group() and setPersonProperties() in native 4.0), a registered $session_id, and copy(debouncerDelayMs = ...) no longer compiling.
  • 2026-11-13 release review: the registered $process_person_profile bullet said identity events get dropped; native 4.0 exempts them (fix: keep a registered personless setting off identity events posthog-android#979, posthog-ios identityEvents), and MIGRATION.md already says so. Also marked the captureAi* config rows nullable (Int?, PostHogCompression?), as in PostHogConfig.
  • FAQ lists macOS.
  • Surveys: a new section (iOS 15+, web, Android with posthog-android-surveys-compose from 0.11.0, not macOS or the JVM), the surveys feature flag in the frontmatter set to true, and the FAQ narrowed to logs. aiObservability stays false, as on Android and iOS: only SDKs with LLM wrappers set it.
  • 2026-11-16: posthog-kmp 0.11.0 shipped with only the surveys option (feat: add surveys option to PostHogConfig posthog-kmp#125), so this page now targets 0.12.0. Compose Multiplatform on iOS now says screens are recorded as one masked block, with ph-no-mask to show them (fix(replay): mask Compose Multiplatform views whole posthog-ios#1074), replacing the ph-no-capture workaround. Adds the surveys (0.11.0) and iosCaptureMethod (0.12.0) config rows.

The checklist and macOS row came from #21741, which is closed. That PR's KMP replay text overlapped with this one, so this PR keeps its own wording.

  • 2026-11-20: iosCaptureMethod defaults to GPU (posthog-kmp@c8dbdf9), unlike the native iOS SDK's .standard. The config row says so, the intro to the table no longer claims every default matches native, and the upgrade checklist's session replay bullet says GPU skips web view pages and Metal content, with STANDARD to keep the previous capture.

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 (no pages moved)

🤖 Generated with Claude Code

Remove the screenshot replay option and wireframe mode, rename
debouncerDelayMs to throttleDelayMs, and add the Xcode 26, macOS 11,
phx_ key and capture v1 proxy path notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets turnipdabeets self-assigned this Nov 5, 2026
@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 20, 2026 09:03PM

Changed pages

Page Source
Kotlin Multiplatform contents/docs/libraries/kmp/index.mdx

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Vale prose linter → found 0 errors, 71 warnings, 7 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/libraries/kmp/index.mdx — 0 errors, 71 warnings, 7 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
21:35 warning Use 'kmp' instead of 'KMP'. Vale.Terms
21:436 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
100:98 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
158:6 warning 'JVM (desktop)' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
173:7 warning 'Configure Compose Desktop release builds' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
217:177 warning 'Gson' is a possible misspelling. PostHogBase.Spelling
217:217 warning 'deserializes' is a possible misspelling. PostHogBase.Spelling
217:327 warning 'Gson' is a possible misspelling. PostHogBase.Spelling
217:356 warning 'Okio' is a possible misspelling. PostHogBase.Spelling
219:170 warning Use 'kmp' instead of 'KMP'. Vale.Terms
221:205 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
282:193 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
301:267 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
308:93 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
321:38 warning Use 'kmp' instead of 'KMP'. Vale.Terms
351:277 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
373:93 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
428:44 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
430:44 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
430:75 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
451:254 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
455:4 warning Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept. PostHogBase.ProductNames
455:4 warning 'Feature flags' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
461:23 warning 'preloaded' is a possible misspelling. PostHogBase.Spelling
493:156 warning 'Wasm' is a possible misspelling. PostHogBase.Spelling
501:1 warning Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept. PostHogBase.ProductNames
550:8 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
550:55 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
558:28 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
558:54 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
610:4 warning Capitalize 'Error Tracking' for PostHog's product. Use 'Error tracking' for the general industry concept. PostHogBase.ProductNames
610:4 warning 'Error tracking' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
645:4 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
645:4 warning 'Session replay' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
647:2 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
665:1 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
665:135 warning Use the Oxford comma before 'and' or 'or' in a list of three or more items. PostHogBase.OxfordComma
669:9 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
669:49 warning 'UIKit' is a possible misspelling. PostHogBase.Spelling
671:294 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
698:16 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
698:81 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
702:137 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
703:26 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
717:277 warning Use 'X' instead of 'x'. Vale.Terms
719:41 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
786:10 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
786:90 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
786:99 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
802:34 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
802:52 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
802:121 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
827:56 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
834:84 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
840:42 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
841:68 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
869:69 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
870:59 warning 'logcat' is a possible misspelling. PostHogBase.Spelling
885:128 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
887:44 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
887:67 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
887:437 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
891:270 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
899:216 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
901:187 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
901:195 warning Use 'iOS' instead of 'ios'. Vale.Terms
902:65 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
907:5 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
907:734 warning 'destructuring' is a possible misspelling. PostHogBase.Spelling
907:789 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
916:4 warning 'FAQ' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
918:30 warning Use 'kmp' instead of 'KMP'. Vale.Terms
924:81 warning Use 'kmp' instead of 'KMP'. Vale.Terms
926:21 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
928:5 warning Use 'kmp' instead of 'KMP'. Vale.Terms
928:33 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

12.21 MiB (+569.4 KiB / +4.8%)

Largest changed named chunks
Chunk Gzip Δ vs master
490bc41e476e65d6e70047bd978778ccbdbc6b56.js 453.3 KiB new
component---src-templates-ui-library-docs-tsx.js 298.1 KiB new
2461c6025d2bedd130ec0d6eb3c75cde5c20a8d5.js 131.3 KiB new
e01beff9.js 77.9 KiB new
d1c09c67.js 68.4 KiB new
49b4b7068874fb7dcec1b52226ab714029d5d40a.js 60.9 KiB new
1fe58427eb479d694d29950a543d39e47969ac6b.js 58.8 KiB new
cfcc9e3efb38a26457e476c440637982c52f7652.js 49.0 KiB new
app.js 1132.0 KiB +43.6 KiB / +4.0%
7875c4c5.js 31.7 KiB new
e90d6e7089cae1aeeb7f639d10b83b4a5acb53f3.js 29.7 KiB new
740846d0b8a7fcb004e98b07aa0e2a91e26d193f.js 23.3 KiB new
cf31b3f00f3e3b512c2c681b9f0ea1360d74f666.js 16.4 KiB new
441c3a0be63aa1ff9bc6a36ad076832610adfaaa.js 12.7 KiB new
76f86eb630920ff4ca2e0a4385b0719fc1a2dd81.js 9.4 KiB new

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

Entrypoint Eager size Budget Modules
✅ app 11.16 MiB (+1245.8 KiB / +12.2%) report-only 1117
Largest modules in the app closure
Module Size
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 1023.8 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/puzzle.mjs 388.5 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
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/basketball-coach.mjs 337.4 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/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules 273.1 KiB
./gatsby-browser.tsx + 60 modules 259.6 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-1.mjs 248.5 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules 240.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs 228.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs 221.7 KiB
./src/hooks/useProduct.ts + 18 modules 164.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).

turnipdabeets and others added 6 commits November 8, 2026 12:15
- onFeatureFlags(), the reloadFeatureFlags PostHogFeatureFlagsLoaded parameter, null payloads for invalid JSON, empty variants as disabled
- set/reset{Person,Group}PropertiesForFlags and PostHogConfig.evaluationContexts
- setAppLanguage() (no-op on JS/Wasm) and $locale as BCP 47 on the JVM
- List the flag changes that reach the web target in the 0.11 upgrade notes
Move the invalid-JSON payload change out of the list that applies to the
web target, which still returns the raw string. Link the full migration
guide and add the missing upgrade items: retries and redirects, the
KotlinMultiplatformLinkedPackage commit, recompiling 0.10 libraries,
posthog-server and surveys-compose versions, $process_person_profile in
beforeSend, event changes, and Compose screens now recorded. Name macOS
alongside Android, iOS and the JVM.

Claude-Session: https://claude.ai/code/session_019xLynttdFZAHfqTem5BhPQ
@eli-r-ph

Copy link
Copy Markdown
Contributor

If PostHog/posthog-kmp#119 lands in 0.11, this page also needs its new API: PostHogEventOptions on the capture calls, registerOptions / unregisterOptions, and captureAi, as the Flutter page covers them for version 6.

turnipdabeets and others added 3 commits November 12, 2026 11:17
…ade notes

Adds the posthog-kmp#119 surface (event options, registerOptions,
PostHogEvent.options, captureAi and its config), corrects the beforeSend
person-processing note, warns about a registered $process_person_profile
and $session_id, notes the copy(debouncerDelayMs) break, and lists macOS
in the FAQ.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Fix the setPersonProperties sample's parameter names and say the
  reloadFeatureFlags callback can run on a background thread.
- Say which 0.11 changes reach the web target, and what registerOptions
  and the identity calls do with options there.
- Add the Java eventOptions break, positional SessionRecordingConfig,
  capture() $process_person_profile, retry, payload and event changes.
- Correct the captureScreenViews, inApp* and beforeSend platform notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread contents/docs/libraries/kmp/index.mdx Resolved
turnipdabeets and others added 2 commits November 13, 2026 17:37
Native 4.0 (posthog-android#979, posthog-ios identityEvents) doesn't apply a
registered $process_person_profile to identify, alias, group and
setPersonProperties, and posthog-kmp's MIGRATION.md says so. The upgrade
checklist still said those events get dropped. Also mark the captureAi*
config rows as nullable, as they are in PostHogConfig.

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

posthog-ios 4.0 records Compose Multiplatform screens (it schedules
captures from the run loop since posthog-ios#896), but it finds what to
mask through UIKit views, so text fields, text and images that Compose
draws are recorded unmasked. Document it and the ph-no-capture
workaround, verified on the iOS simulator against the posthog-ios 4.0
branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
posthog-kmp 0.11.0 shipped with only the surveys option, so the native
4.0 release is 0.12.0. Renumber the page, describe iOS Compose
Multiplatform screens as recorded fully masked with ph-no-mask to show
them (PostHog/posthog-ios#1074), and add the surveys and
iosCaptureMethod config rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets turnipdabeets changed the title docs(kmp): update for posthog-kmp 0.11 docs(kmp): update for posthog-kmp 0.12 Nov 16, 2026
posthog-kmp shows popover surveys on iOS and web, and on Android from
0.11.0 when the app depends on posthog-android-surveys-compose. Mark
surveys as supported, add a Surveys section with the Android dependency
and the surveys option, and narrow the FAQ to logs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gewenyu99 and others added 2 commits November 19, 2026 15:57
posthog-kmp#108 (c8dbdf9) made GPU the default. Update the config row,
note that it differs from the native iOS default, and add it to the
upgrade checklist since GPU capture skips web view pages and Metal.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content PR only touches files under contents/ docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants