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(), use the latest version
plugins {
    id("com.android.application")
    id("com.posthog.android") version "1.5.0"
    ...
}

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.57.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.

The Gradle plugin registers an uploadPostHogNativeSymbols<Variant> task that reads the variant's unstripped native libraries and uploads every one carrying debug info and a build ID. When your app module builds native code (CMake or ndk-build), the task runs automatically after assemble, install, or bundle, for minified and non-minified builds alike.

If your app only bundles prebuilt .so files from dependencies, run the task explicitly:

./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.