USAGE.md

How to use the Android SDK v3

Setup

// app/build.gradle.kts
implementation("com.posthog:posthog-android:$latestVersion")

import com.posthog.PostHog
import com.posthog.android.PostHogAndroid
import com.posthog.android.PostHogAndroidConfig

val config = PostHogAndroidConfig(apiKey)
PostHogAndroid.setup(applicationContext, config)

Set a custom host (Self-Hosted)

val config = PostHogAndroidConfig(apiKey, host)

Change the default configuration

val config = PostHogAndroidConfig(apiKey).apply { 
    captureScreenViews = false
    captureDeepLinks = false
    captureApplicationLifecycleEvents = false
    debug = true
    // .. and more
}

If you don't want to use the global/singleton instance, you can create your own PostHog SDK instance and hold it

val config = PostHogAndroidConfig(apiKey)
val postHog = PostHogAndroid.with(applicationContext, config)

postHog.capture("user_signed_up")

Enable or Disable the SDK to capture events

// During SDK setup
val config = PostHogAndroidConfig(apiKey).apply {
    // the SDK is enabled by default
    optOut = true
}
PostHogAndroid.setup(applicationContext, config)

// At runtime
PostHog.optOut()

// Check it and opt-in
if (PostHog.isOptOut()) {
    PostHog.optIn()
}

Capture a screen view event

// Automatically
val config = PostHogAndroidConfig(apiKey).apply {
    // it's enabled by default
    captureScreenViews = true
}
PostHogAndroid.setup(applicationContext, config)

// Or manually
PostHog.screen("Dashboard", properties = mapOf("url" to "...", "background" to "blue"))

Capture an event

PostHog.capture("user_signed_up", properties = mapOf("is_free_trial" to true))
// check out the `userProperties`, `userPropertiesSetOnce` and `groupProperties` parameters.

Identify the user

PostHog.identify(
    "user123",
    userProperties = mapOf("email" to "[email protected]")
)

Create an alias for the current user

PostHog.alias("theAlias")

Identify a group

PostHog.group("company", "company_id_in_your_db", groupProperties = mapOf("name" to "Awesome Inc."))

Registering and unregistering a context to be sent for all the following events

// Register
PostHog.register("team_id", 22)

// Unregister
PostHog.unregister("team_id")

Load feature flags automatically

import com.posthog.PostHogOnFeatureFlags

val config = PostHogAndroidConfig(apiKey).apply {
    preloadFeatureFlags = true
    // get notified when feature flags are loaded
    onFeatureFlags = PostHogOnFeatureFlags {
        if (PostHog.isFeatureEnabled("paidUser", defaultValue = false)) {
            // do something
        }
    }
}
PostHogAndroid.setup(applicationContext, config)

// And/Or manually
PostHog.reloadFeatureFlags {
    if (PostHog.isFeatureEnabled("paidUser", defaultValue = false)) {
        // do something
    }
}

Read feature flags

val paidUser = PostHog.isFeatureEnabled("paidUser", defaultValue = false)

// Or
val paidUser = PostHog.getFeatureFlag("paidUser", defaultValue = false) as Boolean

Read feature flags variant/payload

val premium = PostHog.getFeatureFlagPayload("premium", defaultValue = false) as Boolean

Read the current distinctId

val distinctId = PostHog.distinctId()

Sanitize event properties

import com.posthog.PostHogPropertiesSanitizer

val config = PostHogAndroidConfig(apiKey).apply {
    propertiesSanitizer = PostHogPropertiesSanitizer { properties ->
        properties.apply {
            // will remove the property from the event
            remove("\$device_name")
        }
    }
}
PostHogAndroid.setup(applicationContext, config)

Flush the SDK by sending all the pending events right away

PostHog.flush()

Reset the SDK and delete all the cached properties

PostHog.reset()

Close the SDK

PostHog.close()

Android Session Recording

Read the Mobile session replay documentation.

Enable Record user sessions on the PostHog project settings.

Install the SDK to capture Session recording.

Install and learn more about Network performance recording.

Learn more about Privacy controls.