[turnipdabeets]

Important

This is the posthog-kmp 0.11 integration PR. Don't merge it until posthog-android 4.0.0 (+ core 7.0.0) and posthog-ios 4.0.0 are published. Merging releases 0.11.0. CI fails until then, only because the pinned versions don't exist yet (iOS Build: "no versions of 'posthog-ios' match the requirement 4.0.0"). As of 2026-11-13, PostHog/posthog-android#871 and PostHog/posthog-ios#873 are both still open (latest releases: android 3.77.1, iOS 3.97.0). All stacked 0.11 PRs are merged into this branch, and main is merged in up to #123.

💡 Motivation and Context

posthog-kmp 0.11 adopts the native 4.0 majors (PostHog/posthog-android#871, PostHog/posthog-ios#873). KMP has no HTTP code of its own, so Android, JVM, iOS and macOS move to capture v1 with them. JS and Wasm stay on posthog-js.

• Analytics events go to capture v1 (/i/v1/analytics/events), and the new captureAi sends AI events to /i/v1/ai/events.
• Per-event options (CaptureOptions.eventOptions, registerOptions(), PostHogEvent.options) and the native property precedence.
• The feature flag API matches native 4.0: PostHogFeatureFlagsLoaded in the reload callback, onFeatureFlags(), flag properties, evaluationContexts.
• Session replay always records masked screenshots: SessionRecordingConfig.screenshot is gone, and throttleDelayMs replaces debouncerDelayMs.

The upgrade guide is MIGRATION.md (0.10 → 0.11). From #123, the release also publishes it as the generated migration page.

Docs and onboarding that ship with this release (merge once 0.11.0 is on Maven Central):

• docs(kmp): update for posthog-kmp 0.11 posthog.com#22013: the KMP library page for 0.11 (replay, event options, captureAi, flags, app language, upgrade checklist).
• docs(replay): update kmp 0.11 and react native plugin 3.0 replay onboarding posthog#125537: KMP replay onboarding (no screenshot, throttleDelayMs, requires 0.11.0). It also carries React Native plugin 3.0 changes; split those out if the two releases don't ship together.

What gets released

Artifact	Bump	Why
com.posthog:posthog-kmp	0.10.0 → 0.11.0	Breaking, released as a minor because the SDK is pre-1.0. Five change intents: adopt-native-4-0, drop-replay-screenshot-option, replay-throttle-delay, feature-flags-native-parity, v1-event-options.

Apps that also pull in posthog-server need 2.25.0 or later, and apps that use posthog-android-surveys-compose declare posthog-android 4.0.0 alongside it. Core 7.0 isn't binary compatible with artifacts built against core 6.x. The changeset and the guide cover both.

Merged into this branch

PR	Change
this PR's first commits	Pin posthog-android 4.0.0, core 7.0.0, posthog-ios 4.0.0; macOS 11 minimum; throttleDelayMs and projectToken in the native mappings; Apple reports posthog-kmp through PostHogSDK.setSdkName instead of stamping $lib in beforeSend; regenerated sample linkage package
#109	Remove SessionRecordingConfig.screenshot
#113	Add throttleDelayMs, deprecate debouncerDelayMs, apply it on iOS too
481ea99 and follow-ups	Match the native 4.0 flag API: PostHogFeatureFlagsLoaded, onFeatureFlags(), set/reset{Person,Group}PropertiesForFlags, evaluationContexts, Apple isFeatureEnabled with defaultValue, empty variant reads as disabled everywhere
#115	PostHog.setAppLanguage(), BCP 47 $locale on JVM
#117	Review follow-ups: web errorsLoading replay, beforeSend person-processing note
#119	Event options, registerOptions()/unregisterOptions() (through the native wrapper-option APIs, PostHog/posthog-android#954 and PostHog/posthog-ios#1045), PostHogEvent.options, captureAi() and its four config options
main	Merged up to #123 (Dokka SDK reference), #120, #121, #118

Release review changes in this PR (2026-11-13)

• Merged main (docs: generate the SDK reference as Markdown with Dokka #123) and mapped the new PostHog members in docs/capabilities.json (7304360). docs: generate the SDK reference as Markdown with Dokka #123's generator stops with PostHog.captureAi is not in docs/capabilities.json on any unmapped member. The release step is best-effort, so the release would still publish, but the reference pages wouldn't regenerate. captureAi, onFeatureFlags, the four *PropertiesForFlags functions and registerOptions/unregisterOptions map to their sdk-specs capabilities; setAppLanguage goes under SDK utils. Ran the generator locally against the native 4.0 builds: it passes, and writes the reference and the migration page.
• Checked the changesets and MIGRATION.md against both native 4.0 descriptions and guides as of today. No gaps: the registered $process_person_profile exemption for identity events (fix: keep a registered personless setting off identity events posthog-android#979, posthog-ios identityEvents), null handling (fix: keep null array elements in event properties posthog-android#955, fix: omit null-valued event properties posthog-ios#1047), $lib kept per event (fix: keep $lib and $lib_version on capture v1 events posthog-android#942, fix: keep $lib and $lib_version on capture v1 events posthog-ios#1036), empty variants (fix(flags): read an empty variant as disabled in getFeatureFlagResult and onFeatureFlags posthog-android#949, fix(flags): read an empty variant as disabled in getFeatureFlagResult and onFeatureFlags posthog-ios#1037) and the 3.77 main merge into android 4.0 (failed flags read as missing) all match.
• docs(kmp): update for posthog-kmp 0.11 posthog.com#22013 still said a registered $process_person_profile drops identify/alias/group events, which native 4.0 changed. Fixed there (PostHog/posthog.com@cdab7ec), with the captureAi* config rows marked nullable as they are in PostHogConfig.
• Native 4.0 APIs KMP doesn't call, so no change needed: iOS PostHogDataMode.cellular, the PostHogConsoleLog* renames, didReceiveFeatureFlags, maxRetries → pushNotificationSubscriptionMaxRetries, screenshotMode. posthog-ios 4.0 is SPM-only, which KMP already uses, and its package traits are on by default.

✅ Before release

• posthog-android 4.0.0 + core 7.0.0 published (feat!: posthog-android 4.0 and posthog 7.0 posthog-android#871, open).
• posthog-ios 4.0.0 tagged (chore!: iOS Major Release 4.0 posthog-ios#873, open; still waiting on the CALayer replay crash fix, docs: sort the iOS 4.0.0 migration guide by when you make each change posthog-ios#1061 and a final main merge).
• Remove the three TODO comments in gradle/libs.versions.toml and the TODO(native-4.0-links) comment in MIGRATION.md, after checking that both native migration guide links (android-v4.0.0, 4.0.0) resolve.
• Re-resolve against the 4.0.0 tag and commit .swiftpm-locks/default/swiftImport/Package.resolved and sample/iosApp/iosApp.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved (both still pin 3.64.1). CI's "Verify committed iOS linkage files" step fails until they do.
• Merge main again, re-run CI, and get an approval. If main added a PostHog member, map it in docs/capabilities.json.
• Optional: a short device smoke test on the published artifacts. The device runs below used the 2026-11-05 native branches and predate feat: add event options, registerOptions and captureAi #119; the unit suites were re-run on 2026-11-13 against the current native heads (see How did you test it?).

Release day, after 0.11.0 is on Maven Central

• Check that the release commit regenerated references/ (best-effort step). If not, run generate-references.yml.
• Mark docs(kmp): update for posthog-kmp 0.11 posthog.com#22013 ready and merge it.
• Merge docs(replay): update kmp 0.11 and react native plugin 3.0 replay onboarding posthog#125537, or only its KMP file if @posthog/react-native-plugin 3.0 isn't out yet.

After release

• Optional: a KMP tab for captureAi in the LLM analytics manual-capture onboarding. docs(onboarding): update android onboarding for posthog-android 4.0 posthog#129665 adds Android, iOS and Flutter tabs only.

🔍 Follow-ups found while testing (not caused by this PR)

• iOS replay records Compose Multiplatform screens unmasked from 0.11 (Session replay doesn't mask text fields inside a Compose Multiplatform view posthog-ios#1072). 0.10's posthog-ios 3.64.1 triggered captures from UIKit layout, so Compose screens got no frames. posthog-ios #896 (3.94.0, in 4.0) captures from the run loop, so 0.11 records them, but the mask walk can't see inside the single Compose view: a Compose TextField was readable with default masking (simulator, 2026-11-13, 1a1205c). ph-no-capture on the Compose view masks it whole. MIGRATION.md, the changeset and docs(kmp): update for posthog-kmp 0.11 posthog.com#22013 now document it. fix(replay): mask Compose Multiplatform views whole posthog-ios#1074 (draft) masks Compose views whole by default; verified end to end on the simulator. Decide before release whether to wait for it in posthog-ios 4.0.
• Web: calling setup() again after close() keeps the first posthog-js instance, so a second projectToken is ignored. Pre-existing on JS/Wasm.

💚 How did you test it?

Built against the native integration branches as of 2026-11-05: posthog-android chore/v4-remove-deprecated @ be3ed4b + #942, published to a local Maven repo as 4.0.0 / core 7.0.0; posthog-ios chore/v4-remove-deprecated @ 3460e53 + #1036 as a local Swift package. The sample was wired to them in a scratch worktree only. Nothing from that wiring is committed.

🤖 Testing locally (native 4.0 isn't published yet)

CI fails here only because posthog-android 4.0.0, core 7.0.0 and posthog-ios 4.0.0 aren't released, so Gradle and SwiftPM can't resolve them. The PR is still testable: point it at the unreleased native branches locally. Don't commit any of this. Verified 2026-11-09: :posthog-kmp:jvmTest, :posthog-kmp:testAndroidHostTest and :posthog-kmp:iosSimulatorArm64Test pass.

Android: publish posthog-android 4.0 (and core 7.0) to mavenLocal:

git clone --depth 1 -b chore/v4-remove-deprecated https://github.com/PostHog/posthog-android.git /tmp/posthog-android
cd /tmp/posthog-android
sed -i.bak 's/^coreVersion=.*/coreVersion=7.0.0/; s/^androidVersion=.*/androidVersion=4.0.0/' gradle.properties
CI=false ./gradlew :posthog:publishToMavenLocal :posthog-android:publishToMavenLocal  # CI=true requires a signing key

Then add mavenLocal() as the first entry of dependencyResolutionManagement { repositories { … } } in settings.gradle.kts. The versions are pinned exactly (4.0.0 / 7.0.0 in gradle/libs.versions.toml), so nothing else changes.

iOS / macOS: in posthog-kmp/build.gradle.kts, point the swiftPackage(…) at the branch:

version = branch("chore/v4-remove-deprecated"),   // was exact(libs.versions.posthog.ios.get())

The build rewrites .swiftpm-locks/; discard those changes too.

Run:

./gradlew :posthog-kmp:jvmTest :posthog-kmp:testAndroidHostTest :posthog-kmp:iosSimulatorArm64Test

Unit tests and builds

Check	Result
jvmTest / testAndroidHostTest	70/70, 54/54
iosSimulatorArm64Test / macosArm64Test	43/43 each
jsBrowserTest / jsNodeTest / wasmJsBrowserTest	58/58, 58/58, 44/44
detekt	Passes
Samples	Android assembleDebug, JVM :sample:run, Wasm distribution, integrateLinkagePackage + Xcode iosApp for simulator and device (both privacy bundles present)

Devices

A scratch scenario in the sample's common code ran the same script on every platform, logged each check, and tagged events with a run ID. Mobile and JVM traffic went through a logging proxy to PostHog US cloud, so the wire format and the stored events were both checked. Each platform ran a main launch and then a restart launch, which force-stops the app first.

Platform	Device	In-app checks	Wire + stored events
Android	Pixel 10a (Android 16, physical)	17/17 + 3/3 restart	✅
Android	Emulator (Android 17)	17/17 + 3/3 restart	✅
iOS	iPhone 14 Pro Max (iOS 26.5.2, physical, direct to cloud)	17/17 + 3/3 restart	✅ stored
iOS	iPhone 17 simulator (iOS 26.4)	17/17 + 3/3 restart	✅
JVM	macOS desktop, with storage left by 0.10 / core 6	17/17 + 3/3 restart	✅
Wasm	Chrome	17/17 (no phx_ step, see follow-ups)	✅ stored

macOS native (macosArm64) is covered by macosArm64Test only; the sample has no native macOS app.

New 4.0 behavior, verified:

• Events go to POST /i/v1/analytics/events (gzip, Authorization: Bearer phc_…, PostHog-Sdk-Info: posthog-kmp/0.10.0) on Android, JVM and iOS. Session replay uploads go to /s/.
• $lib = posthog-kmp, $lib_version = 0.10.0 stay in each event body, can be read in beforeSend, and are stored that way. On iOS this comes from setSdkName.
• A phx_ key disables the SDK: its event never arrived on Android, JVM or iOS.
• An empty event name is dropped locally.
• A register("$os_name", …) super property overrides the SDK's value, and unregister restores it.
• Anonymous events carry the process_person_profile: false capture option instead of a property.
• $session_id is sent as the top-level session_id.
• $locale is en-US everywhere. $app_language is en on iOS. On Android it's fr-FR after cmd locale set-app-locales … fr-FR, and absent without a per-app locale or localeConfig, as designed.
• iOS Application Installed/Opened have $app_version/$app_build and no version/build. Android keeps them.
• A JSON string flag payload ("plain text") decodes to a String. A non-JSON payload can't be created in PostHog (the API rejects it), so the null path rests on the native tests.

Regression, verified:

• Capture with string, int, double, both booleans, a list and a nested map arrives with the right JSON types; null values are dropped.
• beforeSend removes a property, adds one, and drops a named event.
• CaptureOptions groups and timestamp work, and screen() keeps its name over a $screen_name property.
• Flags:
  • getFeatureFlag returns the variant.
  • isFeatureEnabled works with and without defaultValue, and a missing flag returns null or the default.
  • getFeatureFlagResult returns JSON payloads as maps, and getAllFeatureFlags works.
  • reloadFeatureFlags fires its callback, and a person-property flag turns on after identify + reload.
• Identity: identify ($set/$set_once), alias, setPersonProperties, group ($groupidentify), getAnonymousId, getDistinctId and getSessionId all work.
• captureException arrives with a stack trace.
• optOut drops events and optIn resumes them.
• flush works, and super properties persist.
• After a restart, the distinct ID and flags persist. reset() creates a new ID.
• Android retried a failed request (PostHog-Attempt: 2) and delivered it.

Re-run on 2026-11-13 (release review)

At 7304360 (after #119 and the main merge), against the current native heads: posthog-android chore/v4-remove-deprecated @ 7bd8b195 published to mavenLocal as 4.0.0 / core 7.0.0, and posthog-ios chore/v4-remove-deprecated @ ef45d7b. Same local wiring as above, not committed.

Check	Result
jvmTest / testAndroidHostTest	94/94, 61/61
iosSimulatorArm64Test / macosArm64Test	53/53 each
jsNodeTest / wasmJsBrowserTest	73/73, 58/58
detekt	Passes
scripts/generate_markdown.py	Passes; writes the reference and the migration page

Devices weren't re-run.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes. (Updated existing tests for the native signatures; behavior verified on devices as above.)
• I updated the docs if needed. (MIGRATION.md; docs(kmp): update for posthog-kmp 0.11 posthog.com#22013 and docs(replay): update kmp 0.11 and react native plugin 3.0 replay onboarding posthog#125537 merge after the release.)
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm change to generate a change intent file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Claude Opus 5.5) built KMP against the native 4.0 integration branches, fixed the compile and test failures, and ran the device matrix above. It audited both native 4.0 changesets against the KMP API to complete the changesets and write MIGRATION.md, and ran a main baseline to confirm that the iOS Compose replay gap predates this PR. In the 2026-11-13 release review it merged main, mapped the new members for the reference generator, re-checked the changesets and guide against the current native 4.0 PRs, and fixed the posthog.com page.

🤖 Generated with Claude Code

[sampo-s-bot]

⚠️ No changeset detected

No new .sampo/changesets/*.md files were detected in this PR. To add one:

• run sampo add
• follow the prompts to pick the affected packages and describe the change
• commit the generated file to this pull request, and it will be detected automatically

If this PR isn't supposed to introduce any changes (e.g., documentation updates), you can ignore this message.

[posthog]

PostHog Review · Standard · reviewed 2ab12cc: 1 Must fix, 1 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.

[posthog]

PostHog Review · Standard · reviewed 4821ed0: 2 Should fix.

[eli-r-ph]

Two items in the description are stale: #115 already merged into this branch, and Apple isFeatureEnabled now uses the native defaultValue overload.

[turnipdabeets]

@eli-r-ph Right, 0.11 doesn't expose capture options, registerOptions or captureAi yet; it's the native 4.0 bump plus the flag API. Is it OK to ship without them and add them in a follow-up minor, or do they need to be in this release? If they do, I can work on getting them in.

[posthog]

PostHog Review · Standard · reviewed 883184d: 1 Must fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[eli-r-ph]

Hey @turnipdabeets

0.11 doesn't expose capture options, registerOptions or captureAi yet; it's the native 4.0 bump plus the flag API.

🤔 as long as it isn't writing to /i/v1/* endpoints yet than that should be safe. if not, we should chat (could still be safe as additive change after release, but depends...)

[eli-r-ph]

Correction to my earlier note: 0.11 does write to /i/v1/*, because it wraps the native 4.0 SDKs on Android, iOS, macOS and the JVM. That makes 0.11 a capture v1 release, so I think #119 should land in 0.11 too (one binary break instead of two). These need to land with it:

• feat: add event options, registerOptions and captureAi #119, once its review findings are addressed.
• docs(kmp): update for posthog-kmp 0.11 posthog.com#22013: document PostHogEventOptions, registerOptions and captureAi from feat: add event options, registerOptions and captureAi #119.
• docs(api): add capture v1 API reference posthog.com#21385: a Kotlin Multiplatform row (0.11.0 on Android, iOS, macOS and the JVM; JavaScript and Wasm stay on legacy capture). I'll add it once the release date is set.
• PostHog/sdk-specs: a compliance audit for posthog-kmp, like the 4.0 audits for iOS and Android.

Does 0.11 publish the same day as the native 4.0 SDKs?

[turnipdabeets]

Updated the description: #115 is marked merged, and the flags row says Apple isFeatureEnabled uses the native defaultValue overload.

[posthog]

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