references/EXAMPLE.md
PostHog Android Example Project
Repository: https://github.com/PostHog/context-mill Path: basics/android
README.md
PostHog Android example
This is an Android example demonstrating PostHog integration with product analytics, session replay, and error tracking using Kotlin and Jetpack Compose.
This example uses the PostHog Android SDK (posthog-android) to provide automatic PostHog integration with built-in error tracking, session replay, and simplified configuration.
Features
- Product Analytics: Track user events and behaviors
- Session Replay: Record and replay user sessions
- Error Tracking: Automatic error capture and crash reporting
- User Authentication: Demo login system with PostHog user identification
- Event Tracking: Examples of custom event tracking throughout the app
Getting Started
1. Prerequisites
- Android Studio (latest stable version)
- Android SDK (API level 24 or higher)
- JDK 11 or higher
- Gradle 8.0 or higher
- A PostHog account
2. Configure Environment Variables
The PostHog configuration is stored in local.properties (this file is gitignored):
# PostHog configuration
posthog.apiKey=your_posthog_project_token
posthog.host=https://us.i.posthog.com
Alternatively, you can configure PostHog in your build.gradle file:
android {
defaultConfig {
buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"your_posthog_project_token\""
buildConfigField "String", "POSTHOG_HOST", "\"https://us.i.posthog.com\""
}
}
Get your PostHog project token from your PostHog project settings.
3. Build and Run
- Open the project in Android Studio
- Sync Gradle files
- Run the app on an emulator or physical device
Project Structure
├── app/
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/example/posthog/
│ │ │ │ ├── BurritoApplication.kt # Application class with PostHog initialization
│ │ │ │ ├── MainActivity.kt # Main activity
│ │ │ │ ├── ui/
│ │ │ │ │ ├── screens/
│ │ │ │ │ │ ├── LoginScreen.kt # Login screen with user identification
│ │ │ │ │ │ ├── BurritoScreen.kt # Demo feature screen with event tracking
│ │ │ │ │ │ └── ProfileScreen.kt # User profile with error tracking demo
│ │ │ │ │ └── components/ # Reusable UI components
│ │ │ │ └── utils/
│ │ │ │ └── PostHogHelper.kt # PostHog utility functions
│ │ │ ├── res/ # Resources (layouts, strings, etc.)
│ │ │ └── AndroidManifest.xml # App manifest
│ │ └── test/ # Unit tests
│ └── build.gradle # App-level Gradle configuration
├── build.gradle # Project-level Gradle configuration
├── settings.gradle # Gradle settings
└── local.properties # Local configuration (gitignored)
Key Integration Points
Application Initialization (BurritoApplication.kt)
PostHog is initialized in the Application class to ensure it's available throughout the app lifecycle:
class BurritoApplication : Application() {
override fun onCreate() {
super.onCreate()
val posthogConfig = PostHogConfig(
apiKey = BuildConfig.POSTHOG_PROJECT_TOKEN,
host = BuildConfig.POSTHOG_HOST
).apply {
// Enable session replay
sessionReplay = true
// Enable automatic exception capture
captureApplicationLifecycleEvents = true
captureDeepLinks = true
captureScreenViews = true
}
PostHog.setup(this, posthogConfig)
}
}
Key Points:
- PostHog is initialized in
onCreate()to ensure it's initialized as early as possible - Configuration is loaded from
BuildConfig(set inbuild.gradle) - Session replay, lifecycle events, and screen views are enabled
- The Application class must be registered in
AndroidManifest.xml
User Identification (LoginScreen.kt)
Users are identified when they log in:
val posthog = PostHog.getInstance()
fun handleLogin(username: String, password: String) {
// Authenticate user
val success = authenticateUser(username, password)
if (success) {
// Identify the user once on login/sign up
posthog.identify(
distinctId = username,
properties = mapOf(
"username" to username,
"login_method" to "password"
)
)
// Capture login event
posthog.capture("user_logged_in", mapOf(
"username" to username
))
}
}
Key Points:
identify()is called once when the user logs in or signs up- User properties can be set during identification
- Events are captured using
capture()with event names and properties - The
distinctIdshould be a unique identifier for the user
Event Tracking (BurritoScreen.kt)
Custom events are tracked throughout the app:
val posthog = PostHog.getInstance()
fun handleBurritoConsideration() {
// Track custom event
posthog.capture("burrito_considered", mapOf(
"total_considerations" to considerationCount,
"username" to currentUser.username,
"timestamp" to System.currentTimeMillis()
))
// Update user properties
posthog.setUserProperties(mapOf(
"last_burrito_consideration" to System.currentTimeMillis(),
"total_burrito_considerations" to considerationCount
))
}
Key Points:
- Events are captured with
capture()method - Event properties provide context about the event
- User properties can be updated with
setUserProperties() - Properties can be strings, numbers, booleans, or dates
Error Tracking
Errors are captured automatically and can also be tracked manually:
Automatic Error Capture: PostHog automatically captures uncaught exceptions when configured:
val posthogConfig = PostHogConfig(
apiKey = BuildConfig.POSTHOG_PROJECT_TOKEN,
host = BuildConfig.POSTHOG_HOST
).apply {
// Automatic exception capture is enabled by default
captureApplicationLifecycleEvents = true
}
Manual Error Capture:
val posthog = PostHog.getInstance()
try {
// Risky operation
performRiskyOperation()
} catch (e: Exception) {
// Capture exception manually
posthog.captureException(e, mapOf(
"context" to "burrito_consideration",
"user_id" to currentUser.id
))
}
Screen View Tracking
Screen views are automatically tracked when captureScreenViews is enabled. You can also manually track screen views:
val posthog = PostHog.getInstance()
// Manual screen view tracking
posthog.screen("BurritoScreen", mapOf(
"screen_category" to "features",
"user_type" to "premium"
))
Session Replay
Session replay is enabled in the PostHog configuration:
val posthogConfig = PostHogConfig(
apiKey = BuildConfig.POSTHOG_PROJECT_TOKEN,
host = BuildConfig.POSTHOG_HOST
).apply {
sessionReplay = true
sessionReplayConfig = SessionReplayConfig(
maskAllInputs = false, // Set to true to mask all input fields
maskAllText = false // Set to true to mask all text
)
}
Accessing PostHog in Components
PostHog is accessed via the singleton instance:
val posthog = PostHog.getInstance()
posthog.capture("event_name", mapOf("property" to "value"))
The instance is available throughout your application after initialization.
Gradle Configuration
App-level build.gradle
android {
defaultConfig {
// PostHog configuration
buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"${project.findProperty("posthog.apiKey") ?: ""}\""
buildConfigField "String", "POSTHOG_HOST", "\"${project.findProperty("posthog.host") ?: "https://us.i.posthog.com"}\""
}
}
dependencies {
// PostHog Android SDK
implementation 'com.posthog:posthog-android:3.+'
// Other dependencies...
}
Reading from local.properties
The local.properties file is automatically read by Gradle:
def localProperties = new Properties()
localProperties.load(new FileInputStream(rootProject.file("local.properties")))
android {
defaultConfig {
buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"${localProperties.getProperty("posthog.apiKey", "")}\""
buildConfigField "String", "POSTHOG_HOST", "\"${localProperties.getProperty("posthog.host", "https://us.i.posthog.com")}\""
}
}
Best Practices
- Initialize Early: Initialize PostHog in your
Application.onCreate()method - Identify Once: Call
identify()once when the user logs in or signs up - Use Meaningful Event Names: Use clear, descriptive event names (e.g.,
user_logged_ininstead oflogin) - Include Context: Add relevant properties to events for better analysis
- Handle Errors Gracefully: Don't let PostHog errors break your app
- Test in Development: Use a separate PostHog project for development/testing
- Respect Privacy: Be mindful of PII (Personally Identifiable Information) in events and properties
Learn More
app/proguard-rules.pro
# Add project specific ProGuard rules here.
# You can control the set of applied configuration files using the
# proguardFiles setting in build.gradle.
#
# For more details, see
# http://developer.android.com/guide/developing/tools/proguard.html
# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
# public *;
#}
# Uncomment this to preserve the line number information for
# debugging stack traces.
#-keepattributes SourceFile,LineNumberTable
# If you keep the line number information, uncomment this to
# hide the original source file name.
#-renamesourcefileattribute SourceFile
app/src/main/AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.INTERNET" />
<application
android:name=".BurritoApplication"
android:allowBackup="true"
android:dataExtractionRules="@xml/data_extraction_rules"
android:fullBackupContent="@xml/backup_rules"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/Theme.PostHog">
<!-- We have to export the MainActivity to be able to start it from the system launcher.
Ignores added for semgrep. -->
<activity
android:name=".MainActivity"
android:exported="true"
android:label="@string/app_name"
android:theme="@style/Theme.PostHog"
tools:ignore="ExportedActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
app/src/main/java/com/example/posthog/BurritoApp.kt
package com.example.posthog
import android.app.Application
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig
class BurritoApplication : Application() {
override fun onCreate() {
super.onCreate()
// Initialize PostHog early in Application lifecycle
val config = PostHogAndroidConfig(
apiKey = BuildConfig.POSTHOG_PROJECT_TOKEN,
host = BuildConfig.POSTHOG_HOST,
).apply {
debug = true
errorTrackingConfig.autoCapture = true
}
PostHogAndroid.setup(this, config)
}
}
app/src/main/java/com/example/posthog/data/User.kt
package com.example.posthog.data
data class User(
val username: String,
val burritoConsiderations: Int = 0
)
app/src/main/java/com/example/posthog/data/UserRepository.kt
package com.example.posthog.data
import android.content.Context
import android.content.SharedPreferences
import org.json.JSONObject
class UserRepository(context: Context) {
private val prefs: SharedPreferences = context.getSharedPreferences(
PREFS_NAME, Context.MODE_PRIVATE
)
companion object {
private const val PREFS_NAME = "burrito_app_prefs"
private const val KEY_CURRENT_USERNAME = "current_username"
private const val KEY_USER_DATA_PREFIX = "user_data_"
}
fun getCurrentUsername(): String? {
return prefs.getString(KEY_CURRENT_USERNAME, null)
}
fun getUser(username: String): User? {
val json = prefs.getString("$KEY_USER_DATA_PREFIX$username", null) ?: return null
return try {
val obj = JSONObject(json)
User(
username = obj.getString("username"),
burritoConsiderations = obj.getInt("burritoConsiderations")
)
} catch (e: Exception) {
null
}
}
fun saveUser(user: User) {
val json = JSONObject().apply {
put("username", user.username)
put("burritoConsiderations", user.burritoConsiderations)
}.toString()
prefs.edit()
.putString("$KEY_USER_DATA_PREFIX${user.username}", json)
.putString(KEY_CURRENT_USERNAME, user.username)
.apply()
}
fun clearCurrentUser() {
prefs.edit()
.remove(KEY_CURRENT_USERNAME)
.apply()
}
fun getCurrentUser(): User? {
val username = getCurrentUsername() ?: return null
return getUser(username)
}
}
app/src/main/java/com/example/posthog/MainActivity.kt
package com.example.posthog
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.lifecycle.viewmodel.compose.viewModel
import androidx.navigation.compose.currentBackStackEntryAsState
import androidx.navigation.compose.rememberNavController
import com.example.posthog.navigation.NavGraph
import com.example.posthog.navigation.Screen
import com.example.posthog.ui.components.AppHeader
import com.example.posthog.ui.components.BottomNavBar
import com.example.posthog.ui.theme.BackgroundGray
import com.example.posthog.ui.theme.PostHogTheme
import com.example.posthog.viewmodel.AuthViewModel
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent {
PostHogTheme {
BurritoApp()
}
}
}
}
@Composable
fun BurritoApp() {
val navController = rememberNavController()
val viewModel: AuthViewModel = viewModel()
val isAuthenticated by viewModel.isAuthenticated.collectAsState()
val currentUser by viewModel.currentUser.collectAsState()
val navBackStackEntry by navController.currentBackStackEntryAsState()
val currentRoute = navBackStackEntry?.destination?.route
Scaffold(
modifier = Modifier.fillMaxSize(),
topBar = {
AppHeader(
isAuthenticated = isAuthenticated,
username = currentUser?.username,
currentRoute = currentRoute,
onNavigate = { route ->
navController.navigate(route) {
popUpTo(Screen.Home.route)
launchSingleTop = true
}
},
onLogout = {
viewModel.logout()
navController.navigate(Screen.Home.route) {
popUpTo(Screen.Home.route) { inclusive = true }
}
}
)
},
bottomBar = {
BottomNavBar(
isAuthenticated = isAuthenticated,
currentRoute = currentRoute,
onNavigate = { route ->
navController.navigate(route) {
popUpTo(Screen.Home.route)
launchSingleTop = true
}
}
)
},
containerColor = BackgroundGray
) { innerPadding ->
Box(
modifier = Modifier
.fillMaxSize()
.background(BackgroundGray)
.padding(innerPadding)
) {
NavGraph(
navController = navController,
viewModel = viewModel
)
}
}
}
app/src/main/java/com/example/posthog/navigation/NavGraph.kt
package com.example.posthog.navigation
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import com.example.posthog.ui.screens.BurritoScreen
import com.example.posthog.ui.screens.HomeScreen
import com.example.posthog.ui.screens.ProfileScreen
import com.example.posthog.viewmodel.AuthViewModel
sealed class Screen(val route: String) {
object Home : Screen("home")
object Burrito : Screen("burrito")
object Profile : Screen("profile")
}
@Composable
fun NavGraph(
navController: NavHostController,
viewModel: AuthViewModel
) {
val isAuthenticated by viewModel.isAuthenticated.collectAsState()
val currentUser by viewModel.currentUser.collectAsState()
NavHost(
navController = navController,
startDestination = Screen.Home.route
) {
composable(Screen.Home.route) {
HomeScreen(
isAuthenticated = isAuthenticated,
username = currentUser?.username,
onLogin = { username -> viewModel.login(username) }
)
}
composable(Screen.Burrito.route) {
if (!isAuthenticated) {
LaunchedEffect(Unit) {
navController.navigate(Screen.Home.route) {
popUpTo(Screen.Home.route) { inclusive = true }
}
}
} else {
BurritoScreen(
burritoCount = currentUser?.burritoConsiderations ?: 0,
onConsiderBurrito = { viewModel.incrementBurritoCount() }
)
}
}
composable(Screen.Profile.route) {
if (!isAuthenticated) {
LaunchedEffect(Unit) {
navController.navigate(Screen.Home.route) {
popUpTo(Screen.Home.route) { inclusive = true }
}
}
} else {
ProfileScreen(
username = currentUser?.username ?: "",
burritoCount = currentUser?.burritoConsiderations ?: 0
)
}
}
}
}
app/src/main/java/com/example/posthog/ui/components/AppHeader.kt
package com.example.posthog.ui.components
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import com.example.posthog.ui.theme.DarkHeader
import com.example.posthog.ui.theme.ErrorRed
import com.example.posthog.ui.theme.White
@Composable
fun AppHeader(
isAuthenticated: Boolean,
username: String?,
currentRoute: String?,
onNavigate: (String) -> Unit,
onLogout: () -> Unit
) {
Box(
modifier = Modifier
.fillMaxWidth()
.background(DarkHeader)
.padding(horizontal = 16.dp, vertical = 12.dp)
) {
Row(
modifier = Modifier.fillMaxWidth(),
horizontalArrangement = Arrangement.SpaceBetween,
verticalAlignment = Alignment.CenterVertically
) {
// App title
Text(
text = "Burrito App",
color = White,
fontSize = 18.sp
)
// User section (right side)
if (isAuthenticated && username != null) {
Row(
horizontalArrangement = Arrangement.spacedBy(12.dp),
verticalAlignment = Alignment.CenterVertically
) {
Text(
text = username,
color = White,
fontSize = 14.sp
)
Button(
onClick = onLogout,
colors = ButtonDefaults.buttonColors(
containerColor = ErrorRed
),
shape = RoundedCornerShape(4.dp),
contentPadding = PaddingValues(horizontal = 12.dp, vertical = 6.dp)
) {
Text(
text = "Logout",
color = White,
fontSize = 14.sp
)
}
}
}
}
}
}
app/src/main/java/com/example/posthog/ui/components/BottomNavBar.kt
package com.example.posthog.ui.components
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.Person
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.NavigationBarItemDefaults
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.vector.ImageVec