Kotlin Multiplatform
Contents
The PostHog Kotlin Multiplatform (KMP) SDK lets you capture analytics from shared Kotlin code that runs on Android, iOS, the web, and JVM desktop apps. It's a thin wrapper that delegates to the official PostHog SDKs on each target – Android, iOS, JavaScript, and the JVM core library on desktop – so you get native batching, queueing, and session replay behind a single common API.
Early access: This SDK is currently in a
0.xpre-release. The API may change between minor versions until it stabilizes. We'd love your feedback on GitHub.
Install with the wizard
Run this command in your project directory to add PostHog to your Kotlin Multiplatform project. The wizard detects your framework, installs the SDK, and sets up your first events.
Or set it up manually by following the rest of this guide.
Installation
Add the dependency to your shared module's commonMain source set:
If you use a Gradle version catalog, declare it there instead:
You can find the latest version on Maven Central.
Link the iOS Swift package
Note: This setup applies to
posthog-kmp0.5.0 and later and requires Kotlin 2.4.0 or later.
On iOS, the SDK uses Kotlin's Swift Package Manager (SwiftPM) integration to link the native posthog-ios package and copy its resources, including privacy manifests, into your app.
posthog-kmp 0.7.0 and later requires iOS 15 or later. posthog-kmp 0.11.0 and later requires Xcode 26 or later to build, and macOS 11 or later for macOS targets.
After adding the dependency, run the linkage task once from your project root:
Replace iosApp/iosApp.xcodeproj with the path to your Xcode project and :shared with the Gradle module that builds your iOS framework.
The task generates a KotlinMultiplatformLinkedPackage directory and adds it to the Xcode project. Commit the generated package and Xcode project changes. The package is updated automatically when SwiftPM dependencies change. If the first build after a dependency change stops with Synthetic project state updated, run the same build again. You don't need to add posthog-ios to Xcode separately.
Configure the SDK
Initialize PostHog once, early in your app's lifecycle, by calling PostHog.setup() with a PostHogConfig and a platform PostHogContext:
You can find your project token and host in your project settings. For convenience, PostHogConfig.HOST_US and PostHogConfig.HOST_EU are provided as constants for the two PostHog Cloud hosts.
Use your project token (phc_...), not a personal API key. From posthog-kmp 0.11.0, the SDK stays disabled on Android, iOS, macOS and the JVM if projectToken is a personal API key (phx_...).
Note: From
posthog-kmp0.11.0, Android, iOS, macOS and the JVM send events to/i/v1/analytics/events. Ifhostpoints to a reverse proxy or a self-hosted instance, make sure it forwards that path and passes the request headers and PostHog's response through unchanged. Refer to Upgrade to 0.11.0 below for the full list.
Platform-specific setup
The only platform difference is how you build PostHogContext. Everything else – event capture, feature flags, config – is shared code.
Android
Android requires the Application instance, so call setup from your Application class – not from an Activity, whose onCreate re-runs on every recreation (for example, on rotation):
Register the class in your AndroidManifest.xml:
iOS
On iOS, use the no-argument PostHogContext():
Web
On the web, use the no-argument PostHogContext():
JVM (desktop)
On the JVM – for example, a Compose Multiplatform desktop app – use the no-argument PostHogContext():
Configure Compose Desktop release builds
If you package your app with Compose Desktop, add jdk.unsupported and a ProGuard configuration file to the compose.desktop.application block in your app module's build.gradle.kts:
If you already configure nativeDistributions.modules, add jdk.unsupported to the existing list.
Create compose-desktop.pro next to the module's build.gradle.kts:
Compose Desktop creates release distributions with ProGuard and a custom Java runtime built by jlink. The custom runtime doesn't include jdk.unsupported automatically, but Gson uses APIs from this module when it deserializes PostHog's queued events and API models. The ProGuard rules preserve reflection-based PostHog and Gson models, prevent invalid Okio bytecode optimization, and retain the OkHttp resources required at runtime.
You must configure both settings in your application because Compose Desktop owns the application's ProGuard and jlink configuration. Dependencies such as the PostHog KMP SDK can't modify this release packaging configuration.
On the JVM, the SDK persists its offline event queue and identity cache to disk under ~/.posthog-kmp. If user.home isn't set (for example, in some containers), it falls back to the temp directory and logs a warning.
Capturing events
You can send custom events using capture:
You can add properties to any event by passing a properties map:
To attach group context or a custom timestamp to a single event, pass CaptureOptions:
Note: Properties with
nullvalues are dropped before the event is sent, so every platform receives the same event shape.
Event options
From posthog-kmp 0.11.0, settings that tell PostHog how to process an event are sent as event options, apart from its properties. Pass them in CaptureOptions.eventOptions, or in the eventOptions parameter of screen(), identify(), alias(), group(), setPersonProperties(), and captureException(). PostHogEventOptions has the keys:
| Option | Replaces the property |
|---|---|
PostHogEventOptions.PROCESS_PERSON_PROFILE | $process_person_profile |
PostHogEventOptions.COOKIELESS_MODE | $cookieless_mode |
PostHogEventOptions.DISABLE_SKEW_CORRECTION | $ignore_sent_at |
PostHogEventOptions.PRODUCT_TOUR_ID | $product_tour_id |
The legacy properties still work, and an option wins over its property. On Android, iOS, macOS, and the JVM, options are sent as given, so a key not in the table also works. On JavaScript and Wasm, PostHog.js has no options, so the keys in the table are sent as their properties on capture(), screen(), and captureException() events, and other keys are dropped. registerOptions() registers those keys as their properties and drops other keys. identify(), alias(), group(), and setPersonProperties() drop their options there, because PostHog.js sends those events without event properties. PROCESS_PERSON_PROFILE has no effect there, because PostHog.js sets $process_person_profile itself.
AI events
To send AI observability events you build yourself, such as $ai_generation, $ai_span, or $ai_embedding, call captureAi instead of capture. It's available from posthog-kmp 0.11.0 on Android, iOS, macOS, and the JVM. It takes the same arguments as capture and runs the same beforeSend callbacks, then sends the event to PostHog's AI endpoint, which accepts much larger events than capture.
captureAi returns the event's UUID once the event is queued. It returns null when the event isn't queued: the SDK isn't set up, is disabled or opted out, a beforeSend callback dropped the event, or the event is over captureAiMaxEventBytes. On JavaScript and Wasm, it sends nothing and returns null.
- Separate queue. AI events have their own on-disk queue, so large events don't push your other events out. It keeps up to
captureAiMaxQueueSizeevents and at most 50 MiB. Past either limit, the oldest events are dropped. - Size limit. The SDK drops an AI event that's over 8 MiB plus 64 KiB once serialized. Everything you pass is sent as is. The SDK doesn't truncate or redact prompts, outputs, or media.
capturedoesn't reroute AI events.capturenever sends$ai_events to the AI endpoint, so usecaptureAifor them. PostHog drops an event sent withcaptureAiwhose name doesn't start with$ai_.- Reverse proxies.
captureAisends to/i/v1/ai/events. Ifhostpoints to a reverse proxy or a self-hosted instance, it has to serve that path too, with the same headers and responses as/i/v1/analytics/events.
These PostHogConfig settings apply only to captureAi, and are ignored on JavaScript and Wasm:
| Setting | Default | Description |
|---|---|---|
captureAiCompression | PostHogCompression.GZIP | How captureAi request bodies are compressed. Other requests aren't affected. |
captureAiMaxQueueSize | 100 | Maximum number of AI events kept on disk before the oldest are dropped. The 50 MiB limit applies too. |
captureAiTimeout | 60 | Seconds an AI request can go without network activity before it times out. |
captureAiMaxEventBytes | 8454144 (8 MiB + 64 KiB) | Maximum size of a serialized AI event. You can only lower it: a larger value uses the default. |
A value of 0 or less for a numeric setting uses its default.
Filter events before sending
beforeSend is available in PostHog KMP 0.3.0 and later on Android, iOS, JVM, Kotlin/JS, and Kotlin/Wasm, and in 0.6.0 and later on macOS. Use version 0.4.2 or later for the exception behavior described below.
Add one or more PostHogBeforeSend callbacks to PostHogConfig.beforeSend. Return a copied event to modify its name or distinct ID, or to redact properties. Return null to drop the event before the SDK queues it:
Callbacks run synchronously in list order. Each callback receives the event returned by the previous callback. Returning null skips the remaining callbacks. If a callback throws, the SDK drops the event and skips the remaining callbacks.
From posthog-kmp 0.11.0, event.options holds the event's event options, including the ones the SDK set, such as process_person_profile set to false for an anonymous user's event. Return a copy with changed options to change them. On JavaScript and Wasm, options is always null.
Versions 0.3.0 through 0.4.1 ignore a callback exception and continue with the last valid event.
Identifying users
Identifying users is required. Call
posthog.identify('your-user-id')after login to link events to a known user. This is what connects frontend event captures, session replays, LLM traces, and error tracking to the same person — and lets backend events link back too.Use a stable ID from your auth system when possible, not an email or display name. Send those as person properties instead. If your app has no other stable key, email works as a fallback if they are unique. Never a shared literal like
"anonymous"or"user", which pools many people onto one person and corrupts their data. When no ID is available at all, skip the identify and retain the anonymous distinct ID that's automatically assigned.Call
posthog.reset()on logout, so the next person to use the browser doesn't inherit the last one's identity.See our guide on identifying users for how to set this up.
Use identify to associate events with a specific user and, optionally, set person properties:
userPropertiesSetOnce works just like userProperties, except it only sets a property if the user doesn't already have it:
Anonymous and identified events
PostHog captures two types of events: anonymous and identified
Identified events enable you to attribute events to specific users, and attach person properties. They're best suited for logged-in users.
Scenarios where you want to capture identified events are:
- Tracking logged-in users in B2B and B2C SaaS apps
- Doing user segmented product analysis
- Growth and marketing teams wanting to analyze the complete conversion lifecycle
Anonymous events are events without individually identifiable data. They're best suited for web analytics or apps where users aren't logged in.
Scenarios where you want to capture anonymous events are:
- Tracking a marketing website
- Content-focused sites
- B2C apps where users don't sign up or log in
Under the hood, the key difference between identified and anonymous events is that for identified events we create a person profile for the user, whereas for anonymous events we do not.
Important: Due to the reduced cost of processing them, anonymous events can be up to 4x cheaper than identified ones, so we recommended you only capture identified events when needed.
Get the current user's distinct ID
You may find it helpful to get the current user's distinct ID – for example, to check whether you've already called identify for a user. Call getDistinctId(), which returns either the ID automatically generated by PostHog or the one passed to identify():
Alias
Sometimes you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible – for example, if a distinct ID used on the frontend isn't available in your backend. Use alias to assign another distinct ID to the same user:
We strongly recommend reading our docs on alias to best understand how to correctly use this method.
Setting person properties
Besides setting properties during identify, you can set person properties directly with setPersonProperties:
Super properties
Super properties are properties you set once and then send with every subsequent capture call. They're set with PostHog.register, which takes a key and value, and they persist across sessions:
The call above ensures every event sent by the user includes "team_id": 22.
Note: This stores properties against the user's events, not against the user profile itself. To store properties against the person, use
identifyorsetPersonProperties.
To stop sending a super property with events, use unregister:
If you're doing this as part of a user logging out, you can instead call PostHog.reset(), which clears all stored super properties and more.
Setting the app language
Events carry $app_language, the language your app displays. On Android 13 and later, the SDK detects it from the app's localeConfig, and on iOS and macOS from the localizations the app bundle declares. Compose Multiplatform resources declare neither, so on iOS and macOS list your languages under CFBundleLocalizations in Info.plist. Android 6 to 12 and the JVM send no $app_language until you set it.
If your app picks its language some other way, such as an in-app setting, call setAppLanguage() with a BCP 47 language tag at startup and whenever the language changes:
Call setAppLanguage() after PostHog.setup(): on Android and the JVM, a call before setup is dropped. The value is kept in memory only and survives reset(). A $app_language super property set with register() takes precedence. On JavaScript and Wasm, setAppLanguage() does nothing yet, because PostHog.js doesn't support $app_language. To send it there now, call PostHog.register("\$app_language", "pt-BR").
$locale is the device's language. On Android, iOS, and macOS it includes the region, such as de-CH. On the JVM it's a BCP 47 tag that keeps the script, such as zh-Hant-TW.
Feature flags
PostHog's feature flags enable you to safely deploy and roll back new features as well as target specific users and groups with them.
By default, flags are preloaded on setup (preloadFeatureFlags = true). Check whether a flag is enabled:
Get the value of a multivariate flag:
Get a detailed result, including the flag's payload:
On Android, iOS, macOS and the JVM, payload is null when the flag's payload isn't valid JSON, such as plain text or an empty string. On JavaScript and Wasm, it's the raw string. A flag whose variant is an empty string counts as disabled: isFeatureEnabled() returns false and result.enabled is false, while getFeatureFlag() and result.variant still return "".
Get every evaluated flag at once as a map of FeatureFlagResult:
Feature flags are fetched on setup and cached. If a user's properties change (for example, after identify), reload them so they reflect the latest state. The optional callback runs once when the reload finishes and receives a PostHogFeatureFlagsLoaded with the enabled flags (flags), their values (variants), and errorsLoading, which is true when the reload failed and the values are the last known flags:
On Android, iOS, macOS, and the JVM, the callback can run on a background thread. Switch to the main thread before you update UI.
To react every time flags load or change, such as at startup, after identify, group, or reset, and after a reload, register a listener with onFeatureFlags(). If flags have already loaded, it also runs with the current values. You can register before setup, and the listener stays active until you unsubscribe. On Android, iOS, and macOS it runs on the main thread:
Setting properties for flag evaluation
If a flag targets a person or group property that you just set, PostHog may not have processed it yet when flags are evaluated. Send the properties with flag requests so the flag uses them right away. They're stored on the device until you reset them, no event is sent, and flags reload afterwards unless you pass reloadFeatureFlags = false:
Evaluation contexts
To evaluate only the flags tagged for part of your app, set evaluationContexts in PostHogConfig. PostHog then evaluates the flags with at least one of these evaluation tags, plus flags with no evaluation tags:
Experiments (A/B tests)
Since experiments use feature flags, running one is very similar to the feature flag code above:
It's also possible to run experiments without using feature flags.
Group analytics
Group analytics lets you associate a user's events with a group (for example, a company, team, or organization). Read the group analytics guide for more information.
Note: This is a paid feature and is not available on the free plan. Learn more on the pricing page.
Associate the current user's events with a group:
Associate with a group and update that group's properties at the same time:
The name is a special property used in the PostHog UI for the group's name. If you don't specify it, the group key is used instead.
Screen views
Capture a screen view with screen:
You can add properties too:
To automatically capture screen views, set captureScreenViews = true in your config. On Android and iOS, the SDK captures a $screen event for each activity or view controller, so a Compose Multiplatform app with a single one records a single screen. Call screen() for your Compose screens instead. On the web target, it captures $pageview and $pageleave events.
Error tracking
The PostHog Kotlin Multiplatform SDK 0.4.0 and higher can automatically capture unhandled exceptions. First, turn on Enable exception autocapture in your project's Error Tracking settings. This server-side option acts as a kill switch, so the SDK does not automatically capture exceptions when it is disabled.
Then, pass an ErrorTrackingConfig when you initialize PostHog:
On Android, iOS, and JVM, this captures unhandled exceptions. On Kotlin/JS and Kotlin/Wasm, it captures unhandled errors and unhandled promise rejections. It does not capture browser console errors.
Capture handled exceptions with their stack traces by calling captureException:
Follow the Kotlin Multiplatform Error Tracking guide for setup and verification. Upload target-specific debug symbols to get readable stack traces from minified and native builds.
Session replay
Session replay is available on Android and iOS. To enable it, turn on "Record user sessions" in your project settings and pass a SessionRecordingConfig:
Session replay records masked screenshots of your app. Text inputs and images are masked by default, but custom-drawn content such as maps, video or canvas drawing is captured as it appears, so mask it before you ship. posthog-kmp 0.11.0 removed wireframe recording and the screenshot option; remove screenshot from your SessionRecordingConfig when you upgrade. See how mobile replay works.
Compose Multiplatform screens on iOS
On iOS, session replay masks content by finding UIKit views, such as text fields and image views. Compose Multiplatform draws its whole UI into one view, so the SDK can't find the text fields, text, or images inside it, and maskAllTextInputs and maskAllImages don't mask them. Android isn't affected: it masks Compose content.
From posthog-kmp 0.11.0, iOS records Compose Multiplatform screens as they appear, including what users type. Before 0.11.0, iOS didn't record Compose Multiplatform screens at all.
Until the SDK can mask inside Compose on iOS, mask the whole Compose view if it can show sensitive content. Set ph-no-capture as the accessibility identifier of the view controller's view where you create it, usually in your Swift app code:
Recordings then show that view as a black block, and you can still see the session's events, network requests and logs. To leave out iOS altogether, enable sessionRecording only on Android.
On Android, enable experimental mask-alignment verification to help preserve screenshot captures during pixel-only redraws, such as continuously animated content:
verifyScreenshotMaskAlignment defaults to false and only affects Android. It adds view-hierarchy walks during capture, so evaluate its performance in your app. Windows with a Compose root already use verification regardless of this flag; setting it to false doesn't disable verification for those windows. Other platforms ignore this option.
Opt out of data capture
You can opt users out of data capture in two ways.
Opt users out by default by setting optOut to true in your config:
Or opt a user out (and back in) at runtime:
Check whether a user is currently opted out:
Session management
Access the identifiers PostHog uses for the current session:
Flush
You can configure how many events queue before flushing with flushAt.
Setting this to 1 will send events immediately and will use more battery. The default is 20.
You can also manually flush the queue to start sending events immediately instead of waiting for the next batch:
Flushing is best-effort and asynchronous – it starts sending queued events in the background but doesn't wait for the request to finish, so it isn't a delivery guarantee.
Reset after logout
To reset the user's ID and anonymous ID, call reset. Usually you'd do this right after the user logs out:
Close
To flush queued events and release resources during a clean shutdown, call close:
Debug mode
If you're not seeing the events, feature flags, or session replay behavior you expect, enable debug mode to see verbose logs about what the SDK is doing:
All configuration options
Pass these to PostHogConfig when calling setup.
| Option | Type | Default | Description |
|---|---|---|---|
projectToken | String | Required | Your PostHog project token. |
host | String | HOST_US | PostHog instance URL. Use PostHogConfig.HOST_US (https://us.i.posthog.com) or PostHogConfig.HOST_EU (https://eu.i.posthog.com). |
debug | Boolean | false | Enables verbose SDK logging. |
captureApplicationLifecycleEvents | Boolean | true | Captures app open/close lifecycle events (mobile). |
captureScreenViews | Boolean | false | Automatically captures $screen events for activities (Android) and view controllers (iOS), and $pageview and $pageleave events on the web. |
captureDeepLinks | Boolean | true | Captures deep link opens (Android). |
sendFeatureFlagEvent | Boolean | true | Sends $feature_flag_called when a flag is evaluated. |
preloadFeatureFlags | Boolean | true | Fetches feature flags automatically during setup. |
flushAt | Int | 20 | Number of queued events that triggers a flush. |
flushIntervalSeconds | Int | 30 | Maximum delay before queued events are flushed. |
maxQueueSize | Int | 1000 | Maximum number of events kept in the queue. |
maxBatchSize | Int | 50 | Maximum number of events sent in one batch. |
optOut | Boolean | false | Starts with analytics opted out. |
personProfiles | PersonProfiles | IDENTIFIED_ONLY | When person profiles are created: IDENTIFIED_ONLY, ALWAYS, or NEVER. |
sessionRecording | SessionRecordingConfig? | null | Enables and configures session replay (Android and iOS). |
autocapture | Boolean | false | Enables automatic event capture where the native platform supports it. |
beforeSend | List<PostHogBeforeSend> | emptyList() | Modifies or drops events before the SDK queues them. |
errorTracking | ErrorTrackingConfig? | null | Enables and configures Error Tracking. |
capturePushNotificationSubscriptions | Boolean | true | Registers the FCM token at startup when Firebase Messaging is available (Android only). |
capturePushNotificationOpened | Boolean | true | Captures push notification opens automatically (Android only). |
evaluationContexts | List<String>? | null | Evaluates only feature flags with one of these evaluation tags, plus untagged flags. null evaluates every flag. |
captureAiCompression | PostHogCompression? | null (GZIP) | How captureAi request bodies are compressed (Android, iOS, macOS, and JVM). |
captureAiMaxQueueSize | Int? | null (100) | Maximum number of captureAi events kept in their own on-disk queue (Android, iOS, macOS, and JVM). |
captureAiTimeout | Int? | null (60) | Seconds a captureAi request can go without network activity before it times out (Android, iOS, macOS, and JVM). |
captureAiMaxEventBytes | Int? | null (8 MiB + 64 KiB) | Maximum size of a serialized captureAi event. Can only be lowered (Android, iOS, macOS, and JVM). |
Error Tracking options
Pass an ErrorTrackingConfig to PostHogConfig.errorTracking.
| Option | Type | Default | Description |
|---|---|---|---|
autoCapture | Boolean | false | Automatically captures unhandled exceptions. |
inAppIncludes | List<String> | emptyList() | Package or bundle prefixes to mark as in-app frames (Android, JVM, and iOS). |
ignoredExceptionTypes | List<KClass<out Throwable>> | emptyList() | Exception types that the SDK should not capture (Android, JVM, and iOS). |
inAppExcludes | List<String> | emptyList() | Package or bundle prefixes to mark as external frames (iOS and macOS only). |
inAppByDefault | Boolean | true | Marks unmatched stack frames as in-app frames (iOS and macOS only). |
Session recording options
Pass a SessionRecordingConfig to PostHogConfig.sessionRecording. Defaults match the native Android and iOS SDKs.
| Option | Type | Default | Description |
|---|---|---|---|
enabled | Boolean | true | Enables session recording. |
maskAllTextInputs | Boolean | true | Masks all text input values. |
maskAllImages | Boolean | true | Masks all images. |
captureNetworkTelemetry | Boolean | true | Includes network requests in the recording. |
captureLogs | Boolean | false | Captures console and system logs (iOS and web). |
captureLogcat | Boolean | true | Captures Android logcat output (Android only). |
throttleDelayMs | Long | 1000 | Minimum delay in milliseconds between replay snapshots (Android and iOS). Replaces the deprecated debouncerDelayMs. |
verifyScreenshotMaskAlignment | Boolean | false | Experimental mask-alignment verification for Android screenshots. Adds view-hierarchy walks during capture. Compose-rooted windows always use verification. Ignored on other platforms. |
Platform support
| Platform | Status | Backed by |
|---|---|---|
| Android | ✅ | PostHog Android (native) |
| iOS | ✅ | PostHog iOS (native, via SwiftPM) |
| macOS (Apple silicon) | ✅ | PostHog iOS (native, via SwiftPM). Version 0.11.0 and later requires macOS 11 or later. |
| Web | ✅ | PostHog.js |
| JVM (desktop) | ✅ | com.posthog:posthog, the JVM core library the Android SDK is built on |
Because the SDK delegates to the native library on each platform, feature availability and behavior follow the underlying SDK. Session replay is available on Android and iOS; the web target inherits PostHog.js behavior.
On the JVM, event capture, identification, feature flags, groups, error tracking, and super properties are all supported. Mobile and browser-only concepts don't apply, so sessionRecording, captureApplicationLifecycleEvents, captureScreenViews, captureDeepLinks, and autocapture are ignored. The JVM also has no standard app-manifest source, so $app_version, $app_build, and $app_namespace person properties aren't set – feature flags targeting those won't match desktop users.
Upgrade to 0.11.0
Version 0.11.0 uses the native Android 4.0, JVM core 7.0, and iOS 4.0 SDKs. The migration guide on GitHub lists every change. These changes apply on Android, iOS, macOS, and the JVM. Of these, only the Session replay and Replay throttling changes reach the web target, as compile errors in common code. The feature flag changes after the list also apply there.
- Capture endpoint: the SDK sends events to
/i/v1/analytics/events. If you use a reverse proxy or you self-host PostHog, make sure that your proxy or instance serves this path, and/i/v1/ai/eventsif you callcaptureAi. A reverse proxy must also:- Pass these request headers through unchanged:
Authorization,PostHog-Sdk-Info,PostHog-Attempt,PostHog-Request-Id,PostHog-Request-Timestamp,Content-Type,Content-EncodingandUser-Agent. - Return PostHog's response status, body and
Retry-Afterheader unchanged. The SDKs read them to decide which events to retry or drop, and drop the events on a2xxwhose body isn't PostHog's. - Proxy setups from our guides before 29 October 2026 strip
Authorization, so PostHog answers401and drops the events. Update yours from the current guide.
- Pass these request headers through unchanged:
- Retries: until your host serves the path, a
404is 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 as401or403, drop the events. Only307and308redirects to the same origin are followed,3xxresponses are no longer retried,Retry-Afteris capped at 30 seconds, the wait between failed sends doubles with jitter, and a request carries at most about 5 MiB. - Project token: if
projectTokenis a personal API key (phx_...), the SDK disables itself at setup. Use your project token (phc_...). - Super properties: values that you set with
registerreplace the properties that the SDK sets, such as$os_name. A registered$session_idreplaces the SDK's session ID, which can detach events from their session replay. - Registered
$process_person_profile: a$process_person_profile = falseset withregister(), or aprocess_person_profile = falseset withregisterOptions(), now applies to every event except the onesidentify(),alias(),group(), andsetPersonProperties()send. In 0.10 the SDK replaced it with its own value, so it had no effect. Events afteridentify()that get it are still linked to the person and billed as identified events, but don't update the person profile. Remove the registered value and usepersonProfilesinstead: the defaultPersonProfiles.IDENTIFIED_ONLYskips person profiles for anonymous users, andPersonProfiles.NEVERcreates none. - Build requirements: Xcode 26 or later, and macOS 11 or later for macOS targets. Build your Xcode app once and commit the updated
KotlinMultiplatformLinkedPackage, which now pins posthog-ios 4.0. - Binary compatibility: recompile any library built against posthog-kmp 0.10. Its Android and JVM bytecode fails at runtime with
NoSuchMethodError. Java callers ofscreen(),identify(),alias(),group(),setPersonProperties(),captureException(), andnew CaptureOptions(groups, timestamp)must pass the neweventOptionsargument. - Other PostHog artifacts: if the same Android or JVM build uses
posthog-server, use 2.25.0 or later. If it usesposthog-android-surveys-compose, declareposthog-android4.0.0 or later alongside it. - Person processing in
beforeSend: when the SDK doesn't process person profiles for an event, it marks the event with theprocess_person_profileevent option instead of a$process_person_profile = falseproperty.beforeSendreads and changes it inevent.options["process_person_profile"], and setting the$process_person_profileproperty there doesn't turn person processing on. A$process_person_profilethat you pass tocapture()now applies, even withpersonProfiles = PersonProfiles.NEVER. To turn person processing on, set the option inbeforeSend, passCaptureOptions(eventOptions = mapOf(PostHogEventOptions.PROCESS_PERSON_PROFILE to true))tocapture(), callidentify(), or setpersonProfiles = PersonProfiles.ALWAYS. - Event options:
$process_person_profile,$cookieless_mode,$ignore_sent_at, and$product_tour_idhave event options that replace them. The properties still work. - Event changes: events with an empty name, or whose distinct ID
beforeSendblanks, are dropped.$feature_flag_calledfor a missing flag leaves out$feature_flag_response– filter on is not set.Application Installed,Application Updated, andApplication Openedno longer haveversionandbuildon iOS and macOS – use$app_versionand$app_build.$localeis now the device's preferred language and region on Android, iOS, and macOS, such asde-CH, and a BCP 47 tag that keeps the script on the JVM, such aszh-Hant-TW. PostHog drops events whose name or distinct ID is over 200 bytes. On iOS and macOS, anullvalue inside a nested map is left out. On Android and the JVM, anulllist element is sent asnullat its position instead of being removed.$sdk_debug_replay_capture_modeis alwaysscreenshot. Android'sDeep Link Openedleaves out query parameters whose name starts with$. Refer to the migration guide for the full list. - Session replay: recordings are always masked screenshots, and the
screenshotoption is gone. On Android, Compose screens, including Compose Multiplatform UI, are now recorded, which can count against your replay quota. On iOS, Compose Multiplatform screens are now recorded too, but their text fields, text and images aren't masked, so mask the Compose view first. Refer to Compose Multiplatform screens on iOS. Becausescreenshotis gone,SessionRecordingConfigpositional arguments and destructuring shift, so use named arguments. Refer to Session replay. - Replay throttling: use
throttleDelayMsinstead of the deprecateddebouncerDelayMs. The constructor still acceptsdebouncerDelayMs, butcopy(debouncerDelayMs = ...)no longer compiles. - Payloads:
FeatureFlagResult.payloadisnullfor a payload that isn't valid JSON, instead of the raw string. On Android and the JVM, a JSONnullpayload isnullinstead of the string"null". On the web target it's still the raw string.
These feature flag changes also apply to the web target:
reloadFeatureFlagscallback: the callback now receives aPostHogFeatureFlagsLoaded. A lambda that ignores it still compiles, but a function reference or a() -> Unitvalue needs the parameter. Beforesetup, the callback runs right away with no flags anderrorsLoading = true.- Empty variants: a flag whose variant is an empty string is disabled on every platform and is left out of
$active_feature_flags.
FAQ
Which platforms does the KMP SDK support?
Android, iOS, macOS (Apple silicon), web, and JVM (desktop). The SDK is designed for Kotlin Multiplatform projects – including Compose Multiplatform – that share business logic across these targets.
Is this different from the Android SDK?
Yes. The Android SDK is for native Android apps. The KMP SDK is for shared Kotlin code targeting multiple platforms, and it wraps the native Android, iOS, and web SDKs so you can call one common API from commonMain.
Why don't I see surveys or logs?
The KMP wrapper currently exposes event capture, identification, feature flags, group analytics, screen tracking, session replay, and error tracking. Surveys and logs aren't wrapped yet. If you'd like logs support, upvote the logs feature request on GitHub – subscribing to the issue is the best way to follow along.





