Skip to content

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

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

turnipdabeets wants to merge 13 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.11.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.11:

  • 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.11.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.

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.

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 13, 2026 11:46PM

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, 69 warnings, 6 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, 69 warnings, 6 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 'Error tracking' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
610:4 warning Capitalize 'Error Tracking' for PostHog's product. Use 'Error tracking' for the general industry concept. PostHogBase.ProductNames
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
683:115 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
754:10 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
754:90 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
754:99 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
770:34 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
770:52 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
770:121 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
795:56 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
802:84 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
808:68 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
836:69 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
837:59 warning 'logcat' is a possible misspelling. PostHogBase.Spelling
851:128 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
853:44 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
853:67 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
853:437 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
857:270 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
865:216 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
867:187 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
867:195 warning Use 'iOS' instead of 'ios'. Vale.Terms
868:65 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
873:5 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
873:542 warning 'destructuring' is a possible misspelling. PostHogBase.Spelling
873:597 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
882:4 warning 'FAQ' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
884:30 warning Use 'kmp' instead of 'KMP'. Vale.Terms
890:81 warning Use 'kmp' instead of 'KMP'. Vale.Terms
892:21 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
892:32 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
894:5 warning Use 'kmp' instead of 'KMP'. Vale.Terms
894:66 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
894:115 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
894:135 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
894:163 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.22 MiB (+573.4 KiB / +4.8%)

Largest changed named chunks
Chunk Gzip Δ vs master
component---src-templates-ui-library-docs-tsx.js 325.2 KiB new
f2dbc74af55ca99cdd38582a532e602146695d29.js 126.9 KiB new
e01beff9.js 77.9 KiB new
d1c09c67.js 68.4 KiB new
1fe58427eb479d694d29950a543d39e47969ac6b.js 58.8 KiB new
b3896404911e2bb789a64cebda263affb5a7eaef.js 49.0 KiB new
app.js 1130.6 KiB +42.3 KiB / +3.9%
7875c4c5.js 31.7 KiB new
832eca2bd90f47d6886052db15970a4309b6d1e4.js 24.2 KiB new
bee98676a804cfae257c1a3b0f0275ad4a219da8.js 16.4 KiB new
76f86eb630920ff4ca2e0a4385b0719fc1a2dd81.js 9.4 KiB new
d1ee37382485a75581197e428f3a15631c2de6cc.js 8.6 KiB new
0ac16b2a4f38f0508692f6e9f203b6550e76aac2.js 8.5 KiB new
component---src-templates-sdk-sdk-markdown-reference-tsx.js 7.9 KiB new
aa5bd93166710ce0ee5edfad64efa881dce87ccb.js 7.0 KiB new

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

Entrypoint Eager size Budget Modules
✅ app 11.15 MiB (+1235.4 KiB / +12.1%) report-only 1106
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.1 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.4 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 166.5 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 Outdated
- **Retries:** until your host serves the path, a `404` is retried about every 30 seconds, and events stay queued only until a full queue evicts them (`maxQueueSize`, 1000 by default). Other errors that aren't retried, such as `401` or `403`, drop the events. Only `307` and `308` redirects to the same origin are followed, `3xx` responses are no longer retried, `Retry-After` is capped at 30 seconds, the wait between failed sends doubles with jitter, and a request carries at most about 5 MiB.
- **Project token:** if `projectToken` is a personal API key (`phx_...`), the SDK disables itself at setup. Use your project token (`phc_...`).
- **Super properties:** values that you set with `register` replace the properties that the SDK sets, such as `$os_name`. A registered `$session_id` replaces the SDK's session ID, which can detach events from their session replay.
- **Registered `$process_person_profile`:** a `$process_person_profile = false` set with `register()` now applies to every event, including the ones `identify()`, `alias()`, `group()`, and `setPersonProperties()` send. PostHog then drops the `$identify`, `$create_alias`, and `$groupidentify` events and doesn't update the person, and the SDK doesn't report it. Remove the registered value and use `personProfiles` instead.

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.

Once posthog-ios #1067 and posthog-android #979 land, a registered $process_person_profile = false no longer applies to the events identify(), alias(), group() and setPersonProperties() send, so PostHog keeps those events. Can this bullet say registered values skip them instead?

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>

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.

2 participants