references/android.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Android Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/android
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Install the dependency
- Configure PostHog
- Send events
- Set up exception autocapture
- Manually capture exceptions
- Verify error tracking
- Upload mapping files
Install with the wizard
Run this command in your project directory to add PostHog to your Android project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install the dependency
Required
Add the PostHog Android SDK to your
build.gradledependencies:build.gradle
dependencies { implementation("com.posthog:posthog-android:3.+") } -
2
Configure PostHog
Required
Initialize PostHog in your Application class:
SampleApp.kt
class SampleApp : Application() { companion object { const val POSTHOG_PROJECT_TOKEN = "<ph_project_token>" const val POSTHOG_HOST = "https://us.i.posthog.com" } override fun onCreate() { super.onCreate() // Create a PostHog Config with the given project token and host val config = PostHogAndroidConfig( apiKey = POSTHOG_PROJECT_TOKEN, host = POSTHOG_HOST ) // Setup PostHog with the given Context and Config PostHogAndroid.setup(this, config) } } -
3
Send events
Recommended
Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:
Kotlin
import com.posthog.PostHog PostHog.capture( event = "button_clicked", properties = mapOf( "button_name" to "signup" ) ) -
4
Set up exception autocapture
Recommended
Client-side configuration only
Support for remote configuration in the error tracking settings requires SDK version 3.32.0 or higher.
You can autocapture exceptions by setting the
errorTrackingConfig.autoCaptureargument totruewhen initializing the PostHog SDK.Kotlin
import com.posthog.android.PostHogAndroidConfig val config = PostHogAndroidConfig( apiKey = POSTHOG_PROJECT_TOKEN, host = POSTHOG_HOST ).apply { ... errorTrackingConfig.autoCapture = true } ...When enabled, this automatically captures
$exceptionevents when errors are thrown by wrapping theThread.UncaughtExceptionHandlerlistener.Planned features
We currently don't support source code context associated with an exception.
These features will be added in a future release.
-
5
Manually capture exceptions
Optional
It is also possible to manually capture exceptions using the
captureExceptionmethod:Kotlin
PostHog.captureException( exception, properties = additionalProperties )This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.
-
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
-
6
Upload mapping files
Required
Great, you're capturing exceptions! The next step is to upload ProGuard/R8 mapping files so PostHog can deobfuscate your stack traces.
Let's continue to the next section.