Upload mappings for Android

CLI v0.7.4 or later

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://download.posthog.com/cli | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

AGP v8 or later

Automatic mappings uploading is handled through the Gradle build process on Android.

Install the PostHog Android Gradle Plugin on your app's build.gradle.kts file.

// Available through mavenCentral()
plugins {
    id("com.android.application")
    id("com.posthog.android") version "$version"
    ...
}

If you are running this in CI/CD, you can configure the CLI directly on the Gradle task instead of relying on POSTHOG_CLI_HOST, POSTHOG_CLI_PROJECT_ID, and POSTHOG_CLI_API_KEY environment variables:

import com.posthog.android.PostHogCliExecTask

tasks.withType<PostHogCliExecTask> {
    postHogHost = "https://eu.posthog.com"
    postHogProjectId = "my-project-id"
    postHogApiKey = "my-personal-api-key"
}

You can also set postHogExecutable if you want to use a custom posthog-cli path.

Requires PostHog Android SDK 3.60.0 or later with errorTrackingConfig.captureNativeCrashes enabled, Gradle plugin 1.5.0 or later, and CLI 0.7.32 or later.

If your app includes native C or C++ code built with the NDK, upload the .so debug symbols so native crash stack traces resolve to function names, files, and line numbers.

Enable the upload in your app's build.gradle.kts:

posthog {
    uploadNativeSymbols.set(true)
}

When enabled, the Gradle plugin's uploadPostHogNativeSymbols<Variant> task reads the variant's unstripped native libraries and uploads every one carrying debug info and a build ID, automatically after assemble, install, or bundle. This covers native code you build with the NDK as well as .so files bundled from jniLibs or dependencies, for minified and non-minified builds alike. Debuggable variants are skipped, so day-to-day debug builds don't upload symbols.

To include source context around resolved crash frames, also bundle the project sources referenced by the debug info:

posthog {
    uploadNativeSymbols.set(true)
    includeNativeSymbolSources.set(true)
}

You can also run the upload task explicitly, for any variant, without enabling the automatic upload:

./gradlew uploadPostHogNativeSymbolsRelease

You can also upload a directory of .so files directly, without the Gradle plugin:

posthog-cli symbol-sets upload --directory app/build/intermediates/merged_native_libs/release

PostHog matches crash frames to uploaded symbols by each library's GNU build ID, which the NDK emits by default. Each build has its own build ID, so symbols must be re-uploaded for every build you ship.

Native crash events are captured on the next app launch, so event properties like $app_version reflect the app at capture time, not at crash time. If the app updated in between, check the crash's release (matched by build ID) rather than the event's version properties when investigating.