Skip to content

USAGE.md

Latest commit

 

History

History
241 lines (182 loc) · 5.52 KB

USAGE.md

File metadata and controls

241 lines (182 loc) · 5.52 KB

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 "user@posthog.com")
)

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

Android Session Recording

Enable Record user sessions on the PostHog project settings.

Authorized Domains for Replay has to be disabled, for now.

Requires the Android SDK version >= 3.1.0-alpha.1.

Enable the SDK to capture Session Recording.

val config = PostHogAndroidConfig(apiKey).apply {
    // sessionReplay is disabled by default
    sessionReplay = true
    // sessionReplayConfig is optional, they are enabled by default
    sessionReplayConfig.maskAllTextInputs = true
    sessionReplayConfig.maskAllImages = true
    sessionReplayConfig.captureLogcat = true
}

If you don't want to mask everything, you can disable the mask config above and mask specific views using the ph-no-capture tag.

<ImageView
    android:id="@+id/imvAndroid"
    android:layout_width="230dp"
    android:layout_height="391dp"
    android:src="@drawable/android_logo"
    android:tag="ph-no-capture"
/>

Add the PostHogOkHttpInterceptor to your OkHttpClient to capture network requests.

private val client = OkHttpClient.Builder()
    .addInterceptor(PostHogOkHttpInterceptor(captureNetworkTelemetry = true))
    .build()

Limitations

  • Requires Android API >= 26, otherwise it's a NoOp.
  • Not compatible and/or tested with Jetpack Compose yet.
  • It's a representation of the user's screen, not a video recording nor a screenshot.
    • Custom views are not fully supported.
  • WebView is not supported, a placeholder will be shown.