Kotlin Multiplatform Error Tracking installation

  1. Install the dependency

    Required

    Add the PostHog KMP SDK to your shared module's commonMain source set:

    shared/build.gradle.kts
    kotlin {
        sourceSets {
            commonMain.dependencies {
                implementation("com.posthog:posthog-kmp:0.+")
            }
        }
    }

    0.+ resolves to the latest 0.x release. The SDK is a pre-release, so the API can change between minor versions – pin an exact version from Maven Central if you would rather upgrade deliberately. Kotlin/Wasm support requires 0.2.0 or higher.

  2. Configure PostHog

    Required

    Call PostHog.setup() once, early in your app's lifecycle. The config is shared across every target – only the PostHogContext differs per platform.

    Android needs the Application instance, so set PostHog up from your Application class – not from an Activity, whose onCreate re-runs on every recreation (for example, on rotation):

    MyApplication.kt
    import android.app.Application
    import com.posthog.kmp.PostHog
    import com.posthog.kmp.PostHogConfig
    import com.posthog.kmp.PostHogContext
    

    class MyApplication : Application() {
        override fun onCreate() {
            super.onCreate()
    

            PostHog.setup(
                config = PostHogConfig(
                    apiKey = "<ph_project_token>",
                    host = "https://us.i.posthog.com",
                ),
                context = PostHogContext(this),
            )
        }
    }

    Register the class in your AndroidManifest.xml:

    android/src/main/AndroidManifest.xml
    <application android:name=".MyApplication" ...>

  3. Send events

    Recommended

    Once installed, PostHog automatically captures app lifecycle events on Android and iOS. Send an event manually from shared code to test your integration:

    Kotlin
    import com.posthog.kmp.PostHog
    

    PostHog.capture(
        event = "button_clicked",
        properties = mapOf(
            "button_name" to "signup"
        )
    )

  4. Enable exception autocapture in PostHog

    Required

    In your project's Error Tracking settings, enable Enable exception autocapture. This project setting acts as a server-side kill switch, so the SDK does not automatically capture exceptions when it is disabled.

  5. Set up exception autocapture

    Required
    Version requirement

    The error tracking configuration requires PostHog KMP version 0.4.0 or higher.

    Both the project setting from the previous step and errorTracking.autoCapture must be enabled. Replace the PostHog.setup() call from the configuration step with the appropriate example below. The optional inAppIncludes prefixes mark matching stack frames as in-app code on Android, iOS, and JVM. Kotlin/JS and Kotlin/Wasm ignore inAppIncludes.

    Keep this call inside the Application.onCreate() method from the Android configuration example:

    MyApplication.kt
    import com.posthog.kmp.ErrorTrackingConfig
    import com.posthog.kmp.PostHog
    import com.posthog.kmp.PostHogConfig
    import com.posthog.kmp.PostHogContext
    

    PostHog.setup(
        config = PostHogConfig(
            apiKey = "<ph_project_token>",
            host = "https://us.i.posthog.com",
            errorTracking = ErrorTrackingConfig(
                autoCapture = true,
                inAppIncludes = listOf("com.example"),
            ),
        ),
        context = PostHogContext(this),
    )

    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.

  6. Manually capture exceptions

    Optional

    Call PostHog.captureException for handled exceptions or errors caught by your application code. You can include additional properties to help investigate the exception.

    Kotlin
    try {
        riskyOperation()
    } catch (error: Exception) {
        PostHog.captureException(
            throwable = error,
            additionalProperties = mapOf("context" to "checkout_flow"),
        )
    }

  7. Verify error tracking

    Recommended
    Confirm events are being sent to PostHog
    Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
    Activity feed with events
    Check for exceptions in PostHog

  8. Upload debug symbols

    Optional

    If you ship minified or native code on a supported KMP target, upload that target's debug symbols so PostHog can generate accurate stack traces.

    Let's continue to the next section.

    Upload debug symbols

Was this page useful?