Skip to content

Latest commit

 

History

History
192 lines (145 loc) · 3.83 KB

USAGE.md

File metadata and controls

192 lines (145 loc) · 3.83 KB
Raw

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

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

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()