Subchapter 82.1

Android

references/android.mdMarkdown31 KBView on GitHub

AI agents: this is one page from PostHog’s docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt (opens in a new tab)

Android

Android · Instrument Product Analytics · PostHog/skills · Skills Docs

import android.app.Application
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig

class SampleApp : Application() {

    companion object {
        const val POSTHOG_API_KEY = "<ph_project_token>"
        // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
        const val POSTHOG_HOST = "https://us.i.posthog.com"
    }

    override fun onCreate() {
        super.onCreate()

        val config = PostHogAndroidConfig(
            apiKey = POSTHOG_API_KEY,
            host = POSTHOG_HOST
        )
        PostHogAndroid.setup(this, config)
    }
}

import com.posthog.PostHog

PostHog.identify(
    distinctId = distinctID,
    userProperties = mapOf(
        "name" to "Max Hedgehog",
        "email" to "max@hedgehogmail.com"
    ),
    userPropertiesSetOnce = mapOf(
        "date_of_first_log_in" to "2024-03-01"
    ),
)

import com.posthog.PostHogOkHttpInterceptor
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig
import okhttp3.OkHttpClient

val config = PostHogAndroidConfig(
    apiKey = POSTHOG_API_KEY,
    host = POSTHOG_HOST,
).apply {
    tracingHeaders = listOf("api.example.com")
}

PostHogAndroid.setup(this, config)

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(PostHogOkHttpInterceptor())
    .build()

import com.posthog.PostHog

PostHog.capture(
    event = "button_b_clicked",
    properties = mapOf("color" to "blue"),
    userProperties = mapOf(
        "string" to "value1",
        "integer" to 2
    )
)

import com.posthog.PostHog

PostHog.capture(
    event = "button_b_clicked",
    properties = mapOf("color" to "blue"),
    userPropertiesSetOnce = mapOf(
        "string" to "value1",
        "integer" to 2
    )
)

import com.posthog.PostHog

val result = PostHog.getFeatureFlagResult("flag-key")
if (result?.enabled == true) {
    // Do something differently for this user

    // Optional: fetch the payload from the same evaluation result
    val matchedFlagPayload = result.payload
}

import com.posthog.PostHog

val result = PostHog.getFeatureFlagResult("flag-key")
if (result?.variant == "variant-key") { // replace "variant-key" with the key of your variant
    // Do something differently for this user

    // Optional: fetch the payload from the same evaluation result
    val matchedFlagPayload = result.payload
}

import com.posthog.PostHog
import com.posthog.android.PostHogAndroidConfig
import com.posthog.PostHogOnFeatureFlags

// During SDK initialization
val config = PostHogAndroidConfig(apiKey = "<ph_project_token>").apply {
    onFeatureFlags = PostHogOnFeatureFlags {
        if (PostHog.isFeatureEnabled("flag-key")) {
            // do something
        }
    }
}

// And/or after the SDK is initialized
PostHog.reloadFeatureFlags {
    if (PostHog.isFeatureEnabled("flag-key")) {
        // do something
    }
}

import com.posthog.PostHogBootstrapConfig

val config = PostHogAndroidConfig(apiKey = POSTHOG_API_KEY, host = POSTHOG_HOST)
config.bootstrap = PostHogBootstrapConfig(
    distinctId = "distinct_id_of_your_user",
    isIdentifiedId = true,
    featureFlags = mapOf(
        "flag-1" to true,
        "variant-flag" to "control"
    )
)
PostHogAndroid.setup(this, config)

import com.posthog.PersonProfiles
import com.posthog.android.PostHogAndroidConfig

val config = PostHogAndroidConfig(
    apiKey = POSTHOG_API_KEY,
    host = POSTHOG_HOST
).apply {
    captureApplicationLifecycleEvents = true
    captureScreenViews = true
    captureDeepLinks = true

    flushAt = 20
    maxQueueSize = 1000
    maxBatchSize = 50
    maxRetries = 3
    flushIntervalSeconds = 30

    debug = false
    optOut = false

    sendFeatureFlagEvent = true
    featureFlagCalledCacheSize = 1000
    preloadFeatureFlags = true
    evaluationContexts = listOf("production", "android", "mobile")

    setDefaultPersonProperties = true
    personProfiles = PersonProfiles.IDENTIFIED_ONLY
    reuseAnonymousId = false

    sessionReplay = false
    errorTrackingConfig.autoCapture = false
}

Option	Default	Description
`captureApplicationLifecycleEvents`	`true`	Captures `Application Installed`, `Application Updated`, `Application Opened`, and `Application Backgrounded`.
`captureScreenViews`	`true`	Captures `$screen` for foreground `android.app.Activity` screens.
`captureDeepLinks`	`true`	Captures `Deep Link Opened` with URL/query/referrer properties.

Option	Default	Description
`debug`	`false`	Enables verbose SDK logs in Logcat. You can also call `PostHog.debug(true)`.
`optOut`	`false`	Prevents data capture when enabled. You can also call `PostHog.optOut()` and `PostHog.optIn()`.
`flushAt`	`20`	Number of queued events that triggers a flush.
`maxQueueSize`	`1000`	Maximum number of events kept across memory and disk before FIFO eviction.
`maxBatchSize`	`50`	Maximum number of events sent in one batch request.
`maxRetries`	`3`	Maximum retry attempts for failed requests.
`flushIntervalSeconds`	`30`	Maximum delay before queued data is flushed.
`encryption`	`null`	Optional `PostHogEncryption` implementation for encrypting persisted queued events.
`proxy`	`null`	Optional `java.net.Proxy` for PostHog API requests.
`getAnonymousId`	generated UUID	Optional hook to customize anonymous ID generation.
`reuseAnonymousId`	`false`	Reuses one anonymous ID across user changes on the same device.
`personProfiles`	`PersonProfiles.IDENTIFIED_ONLY`	Controls when person profiles are processed: `IDENTIFIED_ONLY`, `ALWAYS`, or `NEVER`.
`setDefaultPersonProperties`	`true`	Includes default device and app properties in feature flag evaluation requests.
`releaseIdentifier`	app/version fallback	Release identifier used by error tracking and uploaded ProGuard/R8 mappings. The Android Gradle plugin can inject this automatically.
`tracingHeaders`	`null`	Exact hostnames that should receive PostHog tracing headers when using `PostHogOkHttpInterceptor`.

Option	Default	Description
`sendFeatureFlagEvent`	`true`	Sends `$feature_flag_called` when a feature flag is evaluated.
`featureFlagCalledCacheSize`	`1000`	Number of feature flag calls cached for deduplicating `$feature_flag_called` events.
`preloadFeatureFlags`	`true`	Fetches feature flags automatically during setup.
`evaluationContexts`	`null`	Context tags that constrain which feature flags are evaluated. Available in version 3.29.1+. The legacy `evaluationEnvironments` option is available in version 3.24.0+.
`onFeatureFlags`	`null`	Callback invoked when feature flags are loaded.

Option	Default	Description
`sessionReplay`	`false`	Enables session replay when project settings also allow recording.
`sessionReplayConfig`	`PostHogSessionReplayConfig()`	Configures masking, screenshots, Logcat capture, sampling, and custom drawable conversion.
`logs`	`PostHogLogsConfig()`	Configures Android logs (opens in a new tab).
`errorTrackingConfig`	`PostHogErrorTrackingConfig()`	Configures error tracking. `autoCapture` defaults to `false`; set it to `true` to autocapture uncaught exceptions when project settings also enable error tracking.
`surveys`	`false`	Internal/experimental native Android survey support. Native Android survey UI is not fully supported or documented yet.
`surveysConfig`	`PostHogSurveysConfig()`	Internal/experimental survey display delegate configuration, primarily for hybrid SDKs.
`bootstrap`	`null`	Seeds identity (`distinctId`, `isIdentifiedId`) and feature-flag state (`featureFlags`, `featureFlagPayloads`) before the first `/flags` response. Bootstrapped identity applies to the first session; only enabled flags are served, until the first `/flags` response replaces them. See SDK bootstrapping (opens in a new tab).

val ignoredScreens = setOf("Splash", "Debug")

config.addBeforeSend { event ->
    val screenName = event.properties?.get("$screen_name") as? String
    if (event.event == "$screen" && screenName in ignoredScreens) {
        null
    } else {
        event
    }
}