PostHog Android SDK
Getting started
The Android SDK runs in Android apps.
To send your first event, add the dependency, then call PostHogAndroid.setup once in Application.onCreate with your project token and host from your project settings.
After setup, PostHog captures app lifecycle events, such as Application Opened, by itself. Use capture for your own events.
Add the SDK to your app's build.gradle.kts:
Initialize it once, in Application.onCreate:
Capture an event and identify the user:
Flush queued events before the app process ends:
Every PostHog.* method below is also available on the instance that PostHogAndroid.with(context, config) returns.
Setup
PostHogAndroid.setup
Sets up the SDK and stores it as the global singleton.
Parameters
context: Android context; the application context is retained internally.config: Android SDK configuration.
PostHogAndroid.with
Creates and returns a configured SDK instance that you can hold and pass around.
Default PostHog integrations are installed only on the first instance created by either setup or with. The first instance in the host app owns those integrations, so setup order matters.
Return
The configured PostHog client instance.
Parameters
context: Android context; the application context is retained internally.config: Android SDK configuration.
Capture
PostHog.capture
Captures events
Parameters
event: the event namedistinctId: the distinctId, the generated distinctId is used if not givenproperties: the custom propertiesuserProperties: the user properties, set as a "$set" property, Docs https://posthog.com/docs/product-analytics/user-propertiesuserPropertiesSetOnce: the user properties to set only once, set as a "$set_once" property, Docs https://posthog.com/docs/product-analytics/user-propertiesgroups: the groups, set as a "$groups" property, Docs https://posthog.com/docs/product-analytics/group-analyticstimestamp: the event timestamp override. UTC is preferred; the equivalent instant is serialized in UTC. If omitted, the current time is used
Identify
PostHog.identify
Identifies the user Docs https://posthog.com/docs/product-analytics/identify
Parameters
distinctId: the distinctIduserProperties: the user properties, set as a "$set" property, Docs https://posthog.com/docs/product-analytics/user-propertiesuserPropertiesSetOnce: the user properties to set only once, set as a "$set_once" property, Docs https://posthog.com/docs/product-analytics/user-properties
Logs
PostHog.captureLog
Captures a single log record into PostHog's logs product, with optional W3C distributed-tracing correlation.
Prefer the logger facade (logger.info, .error, …) for everyday logging. Reach for this entry point when you need to correlate a log with a distributed trace by attaching traceId / spanId / traceFlags.
Parameters
message: the log message body; blank messages are droppedseverity: the log severity, defaults to PostHogLogSeverity.INFOattributes: optional structured attributes; values must be JSON-serializable (String,Number,Boolean,Date, lists or maps of the same)traceId: optional 32-character lowercase hex W3C trace id. The ingestion service zeroes ids that are not exactly 16 bytes.spanId: optional 16-character lowercase hex W3C span id. The ingestion service zeroes ids that are not exactly 8 bytes.traceFlags: optional W3C trace flags bitfield (bit 0 is thesampledflag); emitted on the wire asflags.
PostHog.logger
Captures application log records into PostHog's logs product (separate from product analytics events). Use the severity-specific helpers (PostHogLogger.trace, debug, info, warn, error, fatal) or the generic PostHogLogger.log.
Not to be confused with the internal config.logger debug sink.
Alias
PostHog.alias
Creates an alias for the user Docs https://posthog.com/docs/product-analytics/identify#alias-assigning-multiple-distinct-ids-to-the-same-user
Parameters
alias: the alias
Capture exception
PostHog.captureException
Captures exceptions
Parameters
throwable: the Throwable errorproperties: the custom properties
Debug
PostHog.debug
Enables or disables the debug mode
Parameters
enable: true to enable SDK debug logging, false to disable it.
Exception steps
PostHog.addExceptionStep
Records a breadcrumb-style exception step. A snapshot of the recorded steps is attached to every captured $exception event as $exception_steps, giving the error-tracking UI a timeline of recent activity leading up to each error.
The buffer is a rolling window scoped to the SDK instance: it persists across captures and user identity changes, rotating only by byte-budget eviction (see com.posthog.errortracking.PostHogExceptionStepsConfig).
Recording never throws into the host app: an empty message is ignored with a warning, and internal failures skip the step (logged via the configured logger).
Recording is synchronous: the $timestamp is captured at call time and the step is normalized, byte-budget enforced, and buffered before this method returns, so a step recorded immediately before an exception or crash is present when it is captured. The work is bounded and cheap, adding negligible latency to the caller.
Parameters
message: a non-empty description of the stepproperties: optional user-supplied properties (the reserved keys$messageand$timestampare stripped)
Flush
PostHog.flush
Flushes all the events in the Queue right away
Get anonymous ID
PostHog.getAnonymousId
Returns the anonymous ID generated for this device before any identify call.
Unlike distinctId, this value does not change after identify — it always reflects the pre-identification anonymous identifier. Useful for linking anonymous sessions to identified users in downstream systems.
Return
The anonymous ID, or an empty string if the SDK is not enabled.
Get distinct ID
PostHog.distinctId
Returns the registered distinctId property
Return
The current distinct ID.
Get feature flag
PostHog.getFeatureFlag
Returns the feature flag Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
Return
The feature flag value, or defaultValue if not found.
Parameters
key: the KeydefaultValue: the default value if not foundsendFeatureFlagEvent: (optional) If false, we won't send an $feature_flag_called event to PostHog.
Get feature flag payload
PostHog.getFeatureFlagPayload
Deprecated
Use getFeatureFlagResult() instead; note it sends the $feature_flag_called event by default.
Replace with
Returns the feature flag payload Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
Return
The feature flag payload, or defaultValue if not found.
Parameters
key: the KeydefaultValue: the default value if not found
Get feature flag result
PostHog.getFeatureFlagResult
Returns the feature flag result containing both value and payload. This is the recommended way to access feature flags when you need both the flag value and its payload atomically.
Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
Return
FeatureFlagResult if the flag exists, null otherwise
Parameters
key: The feature flag keysendFeatureFlagEvent: If false, won't send $feature_flag_called event to PostHog
Get feature flags
PostHog.getAllFeatureFlags
Returns list of all feature flag result containing both value and payload. Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
Return
The currently loaded feature flag results, or null when flags are unavailable.
Get session ID
PostHog.getSessionId
Returns the session Id if a session is active
Return
The current session ID, or null if no session is active.
Group
PostHog.group
Creates a group Docs https://posthog.com/docs/product-analytics/group-analytics
Parameters
type: the Group typekey: the Group keygroupProperties: the Group properties, set as a "$group_set" property, Docs https://posthog.com/docs/product-analytics/group-analytics
Is feature enabled
PostHog.isFeatureEnabled
Returns if a feature flag is enabled, the feature flag must be a Boolean Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
Return
Whether the feature flag is enabled.
Parameters
key: the KeydefaultValue: the default value if not found, false if not givensendFeatureFlagEvent: (optional) If false, we won't send an $feature_flag_called event to PostHog.
Is opt out
PostHog.isOptOut
Checks if the optOut mode is enabled or disabled
Is session replay active
PostHog.isSessionReplayActive
Returns if Session Replay is Active Android only.
Return
Whether session replay is currently active.
Opt in
PostHog.optIn
Enables the SDK to capture events
PostHog.optOut
Disables the SDK to capture events until you optIn again
Register
PostHog.register
Register a property to always be sent with all the following events until you call unregister with the same key PostHogPreferences.ALL_INTERNAL_KEYS are not allowed since they are internal and used by the SDK only.
Parameters
key: the Keyvalue: the Value
Reload feature flags
PostHog.reloadFeatureFlags
Reloads the feature flags
Parameters
onFeatureFlags: the callback to get notified once feature flags is ready to use
Reset
PostHog.reset
Resets all the cached properties including the distinctId The SDK will behave as its been setup for the first time
Reset group properties for flags
PostHog.resetGroupPropertiesForFlags
Clears group properties for feature flag evaluation.
Parameters
type: Optional group type to clear. If null, clears all group properties.reloadFeatureFlags: Whether to automatically reload feature flags after resetting properties
Reset person properties for flags
PostHog.resetPersonPropertiesForFlags
Resets all person properties that were set for feature flag evaluation.
Parameters
reloadFeatureFlags: Whether to automatically reload feature flags after resetting properties
Screen
PostHog.screen
Captures a screen view event
Parameters
screenTitle: the screen title. It takes precedence over a$screen_namekey in properties.properties: the custom properties
Set group properties for flags
PostHog.setGroupPropertiesForFlags
Sets properties for a specific group type to include when evaluating feature flags.
Parameters
type: The group type identifier (e.g., "organization", "team")groupProperties: Dictionary of properties to set for this group typereloadFeatureFlags: Whether to automatically reload feature flags after setting properties
Set person properties
PostHog.setPersonProperties
Sets properties on the person profile associated with the current distinct_id. Learn more about identifying users
Updates user properties that are stored with the person profile in PostHog. If personProfiles is set to IDENTIFIED_ONLY and no profile exists, this will create one.
This method sends a $set event to PostHog.
Parameters
userPropertiesToSet: Optional: Properties to store about the user. These will overwrite existing values.userPropertiesToSetOnce: Optional: Properties to store about the user only if not previously set. Note: For feature flag evaluations, if the same key is present in both parameters, the value from userPropertiesToSet will take precedence.
Set person properties for flags
PostHog.setPersonPropertiesForFlags
Sets person properties that will be included in feature flag evaluation requests.
Parameters
userProperties: Dictionary of person properties to include in flag evaluationreloadFeatureFlags: Whether to automatically reload feature flags after setting properties
Shutdown
PostHog.close
Closes the SDK
Start session recording
PostHog.startSessionReplay
Starts session replay. This method will be NoOp if session replay is disabled in your project settings.
Note: This method respects ingestion controls configured in your project settings. If sampling is configured and the session is not sampled, recording will not start. If event triggers are configured, recording will not start until a matching event is captured.
Android only.
Parameters
resumeCurrent: Whether to resume session replay of current session (true) or start a new session (false).
Stop session recording
PostHog.stopSessionReplay
Stops the current session replay if one is in progress.
Android only.
Unregister
PostHog.unregister
Unregisters the previously set property to be sent with all the following events
Parameters
key: the Key
Device ID generator
PostHog.getDeviceId
Returns the stable device identifier used for device-level feature flag bucketing. This ID persists across identify and reset calls, only changing on a fresh app install, manual cache clearing, or OS-initiated storage cleanup.
Return
The device ID, or an empty string if not yet initialized
Session manager
PostHog.endSession
Ends a session The SDK will automatically end a session when you call close On Android, the SDK will automatically end a session when the app is in the background for at least 30 minutes
PostHog.startSession
Starts a session The SDK will automatically start a session when you call setup On Android, the SDK will automatically start a session when the app is in the foreground
SDK utils
PostHog.captureFeatureInteraction
Captures a feature interaction event when a user interacts with a feature.
Parameters
flag: The feature flag keyflagVariant: Optional variant key.
PostHog.captureFeatureView
Captures a feature view event when a user sees a feature in the UI.
Parameters
flag: The feature flag key.flagVariant: Optional variant key.
PostHog.capturePushNotificationOpened
Captures a $push_notification_opened event when the user opens a push notification.
On Android, cold-start taps on a tray notification are captured automatically (from the launch intent) when capturePushNotificationOpened is enabled. Call this manually for the paths auto-detection can't observe — foreground data messages and warm-start onNewIntent.
Each key of payload["posthog"] (accepted as a Map or a JSON string) is attached as a $notification_<key> property.
A notification sent by PostHog is captured once: when payload["posthog"] carries an invocation_id, a repeat with the same invocation_id and action_id within 5 minutes of the first capture is skipped, whether that first capture came from this method or from the SDK's automatic capture. Payloads without a posthog.invocation_id are always captured. Only the 20 most recently captured notifications are remembered, so a host that reports more than that inside the window can capture a repeat of the oldest.
A rerun of that workflow, or a loop back to its push step, sends the pair again as a new notification, and its open counts separately: a payload whose google.message_id differs from the one captured first is captured. Forward the tapped intent's extras (which carry that id) to keep those apart — a payload without one, such as an FCM foreground message.data, is treated as a repeat report of the tap already captured.
Parameters
title: the notification title, attached as$notification_titlewhen non-emptybody: the notification body, attached as$notification_bodywhen non-emptypayload: the notification data payload; itsposthogentry is spread into$notification_*propsaction: the tapped notification action identifier, attached as$notification_action; leavenullfor a plain tap/open (the default action carries no identifier)
PostHog.isSessionActive
Returns if a session is active
Return
Whether a session is currently active.
PostHog.registerPushNotificationToken
Registers a push notification device token with PostHog so the backend can deliver push notifications sent from PostHog Workflows to this device.
The token is persisted and (re)sent with the current distinctId; transient failures are retried automatically. On Android, when Firebase Messaging is on the classpath and capturePushNotificationSubscriptions is enabled, this is called for you at startup. Call it manually to forward Firebase's onNewToken or onRegistered callback. An explicit call refreshes a previously delivered subscription, even when the identifier is unchanged, so a subscription removed after a delivery failure can be restored. Pending registrations retain their retry backoff.
Parameters
deviceToken: the device push token or Firebase Installation ID (FID)appId: the app identifier — the Firebaseproject_idon Android, the APNSbundle_idon iOS
PostHog.unregisterPushNotificationToken
Unregisters this device's push token from PostHog so Workflows stop targeting it — for example from your logout flow.
Sends a DELETE /api/push_subscriptions for the current distinctId (the backend unsets the subscription property) and forgets the locally stored token. The DELETE intent is durable: an offline or transiently failed attempt is persisted and retried passively on the next flush or app launch, the same way registration is. On reset the SDK already moves any registered token to the new anonymous identity (unregister then re-register), independently of capturePushNotificationSubscriptions — that flag only gates automatic token subscription at startup. Call it directly if you manage push subscriptions yourself.
postHogAutocaptureNoCapture
Excludes this element and its descendants from automatic interaction events. Changes to isEnabled apply to subsequent interactions. Does not change session replay masking.
Parameters
isEnabled: Whether to exclude the subtree. Defaults to true; false has no effect.
PostHogAndroid
PostHogAndroid.capturePushNotificationOpened
Captures $push_notification_opened for a notification tap carried on intent.
The SDK reads the tray intent when the launch Activity is created. A host that configures PostHog from its own runtime — Flutter and React Native reach setup() from Dart/JS, after the launch Activity has already created, started and resumed — installs too late to see that callback, and should pass the Activity's intent here instead.
Deduped by google.message_id, so calling it alongside the automatic path cannot double-count, including across a process-death restore: on this path recently opened ids are remembered on disk, because a caller with no savedInstanceState cannot otherwise tell a restore — which hands the Activity back its original intent — from a real second tap. The cost of that trade is that a genuine second tap of the same notification after a process restart reads as a restore and is dropped, until that id ages out of the remembered set.
No-op when intent is null or carries no push id, when capturePushNotificationOpened is disabled, or before setup. Events go to the shared instance, so a host that only called with is not served.
Covers launch intents only. A warm-start tap arrives through Activity.onNewIntent, which nothing here observes — pass that intent in yourself.
Types
FeatureFlagResult
The result of evaluating a feature flag.
Properties
val enabled: Boolean: whether the feature flag is enabledval key: String: the key of the feature flagval payload: Any?: the payload associated with the feature flag (if any)val value: Any: Returns the effective value of the feature flag. For multivariate flags, returns the variant string. For boolean flags, returns the enabled boolean.val variant: String?: the variant of the feature flag (null for boolean flags)
Functions
inline fun <T> getPayloadAs(): T?: Returns the payload deserialized as the specified type.
LinkSurveyQuestion
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval id: String? = nullval link: String?val optional: Boolean? = nullval question: String? = nullval skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = null
MultipleSurveyQuestion
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval choices: List<String>?val description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval hasOpenChoice: Boolean?val id: String? = nullval optional: Boolean? = nullval question: String? = nullval shuffleOptions: Boolean?val skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = null
OnPostHogSurveyClosed
To be called when a survey is dismissed
Parameters
survey: The survey that was closed
OnPostHogSurveyResponse
To be called when a user responds to a survey question
Return
The next question state (next question index and completion flag)
Parameters
survey: The current survey being displayedindex: The index of the question being answeredresponse: The user's response to the question
OnPostHogSurveyShown
To be called when a survey is successfully shown to the user
Parameters
survey: The survey that was displayed
OpenSurveyQuestion
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval id: String? = nullval optional: Boolean? = nullval question: String? = nullval skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = null
PersonProfiles
Controls when captured events should create or update PostHog person profiles.
Entries
NEVER: Never process person profile data. Anonymous users are not merged when they identify.ALWAYS: Process person profile data for all captured events.IDENTIFIED_ONLY: Process person profile data only afteridentify,alias, orgroupcalls.
PostHogAndroidConfig
Android SDK configuration.
Parameters
projectToken: Your PostHog project token, which starts withphc_. Required, no default. Find it in your PostHog project settings: https://us.posthog.com/settings/project-details#variables. Leading and trailing whitespace is trimmed. Formerly namedapiKey. Example:PostHogAndroidConfig(projectToken = "phc_your_project_token").host: PostHog ingestion host. Defaults to DEFAULT_HOST.
Properties
var captureApplicationLifecycleEvents: Boolean: Whether to capture application lifecycle events automatically, including app installed, app updated, app opened, and app backgrounded.var captureDeadClicks: Boolean: Captures$dead_clickwhen a supported target has no observed meaningful UI response for three seconds. Default: false. Bounded local View/Compose change detection may transiently process unmasked UI text; raw text is not retained and neither text nor its ephemeral digest is sent. Unsupported/incomplete observations are skipped. Independent of semantic capture and replay; shares interaction exclusions.var captureDeepLinks: Boolean: Whether to captureDeep Link Openedevents automatically. For warm links delivered tosingleToporsingleTaskactivities, callsetIntent(intent)inActivity.onNewIntentaftersuper.onNewIntent(intent). The SDK checks the current intent on resume and captures each new Intent instance, even if its URL is unchanged. Ordinary resumes do not recapture the same intent. Creation capture, including activity recreation, is unchanged. Default:true.var captureElementInteractions: Boolean: Captures$autocapturefor actionable View and Compose taps. Default: false. Configure before setup. Independent of session replay; sends types and resource IDs/test tags and window-local touch coordinates in dp, never text, content descriptions or input values. Use only non-sensitive test tags. Exclude a View subtree withcom.posthog.android.R.id.posthog_autocapture_no_captureset to true, or use postHogAutocaptureNoCapture for Compose.var capturePushNotificationOpened: Boolean: Whether to auto-capture$push_notification_openedfor cold-start taps on a tray notification (detected via the launch intent'sgoogle.message_idextra). A warm-start tap arrives atActivity.onNewIntent, which is not observable here — forward that intent to PostHogAndroid.capturePushNotificationOpened, which is deduped against this path. Foreground data messages and push delivered outside FCM need PostHog.capturePushNotificationOpened, which dedupes only notifications sent by PostHog. Also gates PostHogAndroid.capturePushNotificationOpened. Default:true.var capturePushNotificationSubscriptions: Boolean: Whether to auto-register this device's push token at startup. When enabled and Firebase Messaging is on the classpath, the SDK fetches the FCM token + Firebaseproject_idand registers them so PostHog Workflows can deliver push notifications. When the manifest enablesfirebase_messaging_installation_id_enabled, the Firebase Installation ID is registered instead. No effect when Firebase is absent (a single debug log). Instant token refresh still needs the app to forwardonNewToken(or, in installation ID mode,onRegistered) toregisterPushNotificationToken(...). Default:true.var captureRageClicks: Boolean: Captures$rageclickafter four nearby taps on the same target within one second. Default: false. Independent of semantic capture and replay; shares their interaction exclusions and privacy-safe properties.var captureScreenViews: Boolean: Whether to capture a$screenevent whenever a foreground Activity starts (viaActivityLifecycleCallbacks.onActivityStarted). When enabled, the most recent screen name is also attached as$screen_nameto every subsequent event captured by the SDK. To opt out of$screen_namestamping entirely, set this tofalseand avoid callingPostHog.screen(...)manually. Default:true.var sessionReplayConfig: PostHogSessionReplayConfig: Android-specific session replay capture options.
PostHogBeforeSend
Hook invoked before an analytics event is queued.
Return the same or a modified PostHogEvent to continue, or null to drop the event.
Functions
fun run(event: PostHogEvent): PostHogEvent?: Runs the hook for event.
PostHogBeforeSendLog
Hook that runs on every captured log record before it is enqueued.
Return null to drop the record, return the (possibly mutated) record to keep it. Multiple hooks compose left-to-right; if any returns null, later hooks are skipped. Registered via PostHogLogsConfig.addBeforeSend.
Runs synchronously on the thread that called the logger — keep work fast (no network, no disk).
Kotlin (SAM)
Java
See also
PostHogLogsConfig.addBeforeSend:PostHogLogsConfig.removeBeforeSend:
Functions
fun run(record: PostHogLogRecord): PostHogLogRecord?: Called once per captured record. Return the record (possibly with a mutated copy via PostHogLogRecord.copy) to keep it, ornullto drop it.
PostHogBootstrapConfig
Pre-seeded identity and feature-flag state applied before any network request completes: identity only on the very first SDK launch, and the feature-flag base layer on every launch until reset().
Set PostHogConfig.bootstrap before calling setup to seed the distinct id and feature flag state. Events captured synchronously during initialization then carry a caller-controlled $distinct_id rather than the SDK-generated UUID, and feature-flag reads return caller-provided values before the first /flags response. Mirrors the bootstrap option in posthog-js.
Bootstrap identity applies to the very first session. An anonymous bootstrap (isIdentifiedId false) seeds the anonymous id only when none is persisted, and is otherwise ignored. An identified bootstrap (isIdentifiedId true) seeds the distinct id on a fresh install; if a local anonymous user already exists it is merged into the identified id via identify(), while a different already-identified user is preserved and a warning is logged. Bootstrapped feature flags are an initial snapshot, not a permanent base: they win over any persisted flag cache at setup and are served until the first /flags response, which then replaces them entirely — a complete response drops bootstrapped-only keys, while only a partial or errored response preserves the keys it did not recompute. reset() drops the snapshot.
Properties
val distinctId: String? = null: The distinct id to seed on first launch.val featureFlagPayloads: Map<String, Any?>? = null: JSON payloads paired with featureFlags, keyed by flag key. Each value is the already-decoded payload (map, list, string, number, ...).val featureFlags: Map<String, Any>? = null: Feature flag values served until the first/flagsresponse arrives, keyed by flag key. Each value is a Boolean for boolean flags or a String for multivariate flags. Only enabled values are served —trueor a non-empty String; afalseor empty-string entry is treated as not bootstrapped (matching posthog-js's!!valuecheck) and dropped, indistinguishable from a key that was never provided. Values must be JSON-serializable; any non-serializable entry (e.g. NaN) is dropped with a logged warning rather than surfaced.val isIdentifiedId: Boolean = false: Whether distinctId represents an already-identified user.
PostHogCompression
Controls whether request bodies are compressed before being sent to the PostHog API.
Entries
GZIP: Gzip request bodies.NONE: Send request bodies uncompressed.
PostHogConfig
The SDK Config
Properties
val apiKey: String: Deprecated alias for projectToken; returns the same trimmed value.val beforeSendList: List<PostHogBeforeSend>: The beforeSend listvar bootstrap: PostHogBootstrapConfig?: Optional bootstrap configuration that seeds identity and feature-flag state before any network request completes. Identity is seeded only on the very first launch, when nothing has been persisted yet. The feature-flag snapshot is applied on every launch as the initial layer — served immediately and taking precedence over any persisted flag cache — until the first/flagsresponse replaces it (a complete response drops bootstrapped-only keys; a partial or errored one keeps the keys it did not recompute) orreset()drops it. See PostHogBootstrapConfig for the precedence rules.var compression: PostHogCompression: How the SDK compresses request bodies before sending them to the PostHog API.var debug: Boolean: Logs the debug logs to the logger if enabled Defaults to false@Volatilevar disableGeoIp: Boolean: Skip server-side GeoIP enrichment for captured events and feature flag requests. When enabled, the server won't infer the user's location from their IP address.var encryption: PostHogEncryption?: Hook for encrypt and decrypt events Devices are sandbox so likely not needed Defaults to no encryptionval errorTrackingConfig: PostHogErrorTrackingConfig: Configuration for PostHog Error Tracking feature.var evaluationContexts: List<String>?: Optional list of evaluation context tags for feature flag evaluation When specified, only feature flags that have at least one matching evaluation tag will be evaluated Feature flags with no evaluation tags will always be evaluated for backward compatibility Example: listOf("production", "web", "checkout") Defaults to null (evaluate all flags)var evaluationEnvironments: List<String>?: Optional list of evaluation environment tags for feature flag evaluationvar featureFlagCalledCacheSize: Int: Maximum number of distinct feature flag calls to cache for deduplication When the cache is full, the least recently used entries are evicted Defaults to 1000var featureFlagRequestMaxRetries: Int: Maximum number of retries for feature flag requests after transient network errors. Defaults to 1. Set to 0 to disable feature flag request retries.var flushAt: Int: Number of minimum events before they are sent over the wire Defaults to 20var flushIntervalSeconds: Int: Interval in seconds for sending events over the wire The lower the number, most likely more battery is used Defaults to 30svar getAnonymousId: (UUID) -> UUID: Hook that allows for modification of the default mechanism for generating anonymous id (which as of now is just random UUID v7)val host: String: The PostHog Host Defaults to https://us.i.posthog.com EU Host: https://eu.i.posthog.comval integrations: List<PostHogIntegration>: The integrations listvar logs: PostHogLogsConfig: Configuration for the logs subsystem. See PostHogLogsConfig for per-field mutability semantics — resource attributes and theflushAt/maxBatchSizeknobs are snapshotted at setup; thebeforeSendchain,maxBufferSize, andflushIntervalSecondsremain live.var maxBatchSize: Int: Number of maximum events in a batch call Defaults to 50var maxQueueSize: Int: Number of maximum events in memory and disk, when the maximum is exceed, the oldest event is deleted and the new one takes place Defaults to 1000var maxRetries: Int: Maximum number of retries for push subscription registration failures.var onFeatureFlags: PostHogOnFeatureFlags?: Hook that is called when feature flags are loaded Defaults to no callback@Volatilevar optOut: Boolean: This flag prevents capturing any data if enabled You can overwrite this value at runtime by calling PostHog.optIn or PostHog.optOut Defaults to falsevar personProfiles: PersonProfiles: Determines the behavior for processing user profiles.var preloadFeatureFlags: Boolean: Preload feature flags automatically Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments Defaults to trueval projectToken: String: Your PostHog project token, trimmed of leading and trailing whitespace.var propertiesSanitizer: PostHogPropertiesSanitizer?: Hook that allows to sanitize the event properties The hook is called before the event is cached or sent over the wirevar proxy: Proxy?: Configures an optional HTTP proxy for the PostHog API client.var pushIdentityProvider: (distinctId: String, appId: String, completion: (String?) -> Unit) -> Unit?: Hook that supplies a signed identity token for push subscription requests, enabling the optional identity verification of the push subscriptions API.var releaseIdentifier: String?: The release identifier used to identify the correct proguard mappings (mapping.txt) in order to make minified stack traces into human readable stack tracesvar remoteConfig: Boolean: Preload PostHog remote config automatically Defaults to trueval remoteConfigProvider: (PostHogConfig, PostHogApi, ExecutorService, PostHogDefaultPersonPropertiesProvider?, PostHogOnRemoteConfigLoaded?, PostHogFeatureFlagCalledProvider?) -> PostHogFeatureFlagsInterface: Factory to instantiate a custom com.posthog.internal.PostHogRemoteConfigInterface implementation.@Volatilevar requestHeaders: Map<String, String>: Custom headers to send with every request to the PostHog API.var reuseAnonymousId: Boolean: Flag to reuse the anonymous id. If enabled, the anonymous id will be reused acrossidentify()andreset()calls.var sendFeatureFlagEvent: Boolean: Send a $feature_flag_called event when a feature flag is used automatically Used by experimentsvar sessionReplay: Boolean: Enable Recording of Session Replays for Android Requires Record user sessions to be enabled in the PostHog Project Settings Defaults to falsevar setDefaultPersonProperties: Boolean: Automatically set common device and app properties as person properties for feature flag evaluation.var surveys: Boolean: Enable Surveys for Android (Intended for internal use only)var surveysConfig: PostHogSurveysConfig: Configuration for PostHog Surveys feature. (Intended for internal use only)var tracingHeaders: List<String>?: When set, PostHog injects tracing headers into OkHttp requests whose destination hostname exactly matches one of the configured hostnames.
Functions
fun addBeforeSend(beforeSend: PostHogBeforeSend): Adds a new PostHogBeforeSendfun addIntegration(integration: PostHogIntegration): Adds a new integrationfun removeBeforeSend(beforeSend: PostHogBeforeSend): Removes the PostHogBeforeSendfun removeIntegration(integration: PostHogIntegration): Removes the integration
PostHogDisplayChoiceQuestion
Represents a question where users can select one or more choices
Properties
val buttonText: String?: Optional custom text for the question's action buttonval choices: List<String>: The list of options for the user to choose fromval hasOpenChoice: Boolean: Whether the question includes an "other" option for users to input free-form textval id: String: The main question idval isMultipleChoice: Boolean: Whether the user can select multiple optionsval isOptional: Boolean: Whether the question can be skippedval question: String: The main question text to displayval questionDescription: String?: Optional additional description or context for the questionval questionDescriptionContentType: PostHogDisplaySurveyTextContentType: Content type for the question description (HTML or plain text)val shuffleOptions: Boolean: Whether the options should be shuffled when presentedval skipSubmitButton: Boolean = false: Whether to auto-submit single choices without an open-ended option
PostHogDisplayLinkQuestion
Represents a question with a clickable link
Properties
val buttonText: String?: Optional custom text for the question's action buttonval id: String: The main question idval isOptional: Boolean: Whether the question can be skippedval link: String?: The URL that will be opened when the link is clickedval question: String: The main question text to displayval questionDescription: String?: Optional additional description or context for the questionval questionDescriptionContentType: PostHogDisplaySurveyTextContentType: Content type for the question description (HTML or plain text)
PostHogDisplayOpenQuestion
Represents an open-ended question where users can input free-form text
Properties
val buttonText: String?: Optional custom text for the question's action buttonval id: String: The main question idval isOptional: Boolean: Whether the question can be skippedval question: String: The main question text to displayval questionDescription: String?: Optional additional description or context for the questionval questionDescriptionContentType: PostHogDisplaySurveyTextContentType: Content type for the question description (HTML or plain text)
PostHogDisplayRatingQuestion
Represents a rating question where users can select a rating from a scale
Properties
val buttonText: String?: Optional custom text for the question's action buttonval id: String: The main question idval isOptional: Boolean: Whether the question can be skippedval lowerBoundLabel: String: The label for the lower bound of the rating scaleval question: String: The main question text to displayval questionDescription: String?: Optional additional description or context for the questionval questionDescriptionContentType: PostHogDisplaySurveyTextContentType: Content type for the question description (HTML or plain text)val ratingType: PostHogDisplaySurveyRatingType: The type of rating scale (numbers, emoji)val scaleLowerBound: Int: The lower bound of the rating scaleval scaleUpperBound: Int: The upper bound of the rating scaleval skipSubmitButton: Boolean = false: Whether selecting a rating submits without an extra submit tapval upperBoundLabel: String: The label for the upper bound of the rating scale
PostHogDisplaySurvey
Represents a survey that is ready to be displayed to the user. Contains all the necessary information for rendering the survey UI.
Properties
val appearance: PostHogDisplaySurveyAppearance? = null: The appearance configuration for the surveyval endDate: Date? = null: Optional date indicating when the survey should stop being shownval id: String: The unique identifier of the surveyval initialQuestionIndex: Int = 0: The question to show when restoring unfinished progress; zero for a new survey.val questions: List<PostHogDisplaySurveyQuestion>: The list of questions in the surveyval startDate: Date? = null: Optional date indicating when the survey should start being shown
PostHogDisplaySurveyAppearance
Represents the appearance configuration for a survey.
Properties
val backgroundColor: String? = null: Optional background color as web color (e.g. "#FFFFFF" or "white")val borderColor: String? = null: Optional border color as web colorval descriptionTextColor: String? = null: Optional color for description text as web colorval displayIntroScreen: Boolean = false: Whether to show an intro screen before the first questionval displayThankYouMessage: Boolean = false: Whether to show a thank you message after survey completionval fontFamily: String? = null: Optional font family to use throughout the surveyval inputBackground: String? = null: Optional background color for input fields as web colorval inputTextColor: String? = null: Optional text color for input fields as web colorval introScreenButtonText: String? = null: Optional custom text for the button that advances past the intro screenval introScreenDescription: String? = null: Optional description text for the intro screenval introScreenDescriptionContentType: PostHogDisplaySurveyTextContentType? = null: Optional content type for the intro screen descriptionval introScreenHeader: String? = null: Optional header text for the intro screenval placeholder: String? = null: Optional placeholder text for input fieldsval ratingButtonActiveColor: String? = null: Optional color for active/selected rating buttons as web colorval ratingButtonColor: String? = null: Optional color for rating buttons as web colorval submitButtonColor: String? = null: Optional background color for the submit button as web colorval submitButtonText: String? = null: Optional custom text for the submit buttonval submitButtonTextColor: String? = null: Optional text color for the submit button as web colorval surveyPopupDelaySeconds: Double? = null: Optional delay, in seconds, before the survey is shown after it is triggeredval textColor: String? = null: Optional primary text color as web colorval thankYouMessageCloseButtonText: String? = null: Optional custom text for the thank you message close buttonval thankYouMessageDescription: String? = null: Optional description text for the thank you messageval thankYouMessageDescriptionContentType: PostHogDisplaySurveyTextContentType? = null: Optional content type for the thank you message descriptionval thankYouMessageHeader: String? = null: Optional header text for the thank you message
PostHogDisplaySurveyQuestion
Base class for all survey question types
Inheritors
PostHogDisplayOpenQuestion:PostHogDisplayLinkQuestion:PostHogDisplayRatingQuestion:PostHogDisplayChoiceQuestion:
Properties
val buttonText: String?: Optional custom text for the question's action buttonval id: String: The main question idval isOptional: Boolean: Whether the question can be skippedval question: String: The main question text to displayval questionDescription: String?: Optional additional description or context for the questionval questionDescriptionContentType: PostHogDisplaySurveyTextContentType: Content type for the question description (HTML or plain text)
PostHogDisplaySurveyRatingType
Type of rating display for survey rating questions
Properties
val value: Int
Entries
NUMBER: Display numeric rating optionsEMOJI: Display emoji rating options
PostHogDisplaySurveyTextContentType
Content type for text-based survey elements (e.g Question description, Thank you message description)
Properties
val value: Int
Entries
HTML: Content should be rendered as HTMLTEXT: Content should be rendered as plain text
PostHogEncryption
Interface for encrypt and decrypt events, by default there's no encrypt since Android is sandboxed https://source.android.com/docs/security/app-sandbox
Functions
fun decrypt(inputStream: InputStream): InputStream: Decrypts data read from inputStream.fun encrypt(outputStream: OutputStream): OutputStream: Encrypts data written to outputStream.
PostHogErrorTrackingAutoCaptureIntegration
Functions
@Synchronizedopen override fun install(postHog: PostHogInterface): Install the Integration after the SDK is setup that requires a posthog instance to capture eventsfun onChange(): Invalidates pending observations when identity, consent, screen, session or close state changes. Called synchronously on the caller's thread; calls may be nested or concurrent. This is a one-shot notification, not a pause/resume boundary. Uninstall must independently clean up.fun onRemoteConfig(loaded: Boolean): Called when the remote config attempt for the current identity resolves. Each integration is responsible for enabling or disabling features based on the state of the remote config.fun uncaughtException(thread: Thread, throwable: Throwable)@Synchronizedopen override fun uninstall(): Uninstall the Integration after the SDK is closed
PostHogErrorTrackingConfig
Configuration for PostHog error tracking.
Properties
var autoCapture: Boolean: Enable autocapture of exceptions This feature installs an uncaught exception handler (Thread.UncaughtExceptionHandler) that will capture exceptionsvar captureNativeCrashes: Boolean: Capture native (NDK) crashes from previous runs of the app.val exceptionSteps: PostHogExceptionStepsConfig: Configuration for exception steps (breadcrumb-style context records attached to every captured$exceptionevent as$exception_steps).val ignoredExceptionTypes: MutableList<Class<out Throwable>>: Throwable classes to drop during capture. The throwable and every cause in its chain are matched via Class.isInstance. Also applies to$exceptionevents sent through the generic capture path (matched by class name).val inAppExcludes: MutableList<String>: List of package names to be excluded from inApp frames for error trackingval inAppIncludes: MutableList<String>: List of package names to be considered inApp frames for error tracking
PostHogEvent
The PostHog event data structure accepted by the batch API
Properties
@SerializedName(value = "api_key")var apiKey: String?@SerializedName(value = "distinct_id")val distinctId: String: The distinct Idval event: String: The event name@SerializedName(value = "message_id")val messageId: UUID? = nullval properties: MutableMap<String, Any>? = null: All the event properties@SerializedName(value = "$set")val set: Map<String, Any>? = nullval timestamp: Date: The event timestamp. UTC is preferred; the equivalent instant is serialized in UTCval type: String? = nullval uuid: UUID?: the UUID v4 is automatically generated and used for deduplication
Functions
fun isExceptionEvent(): Boolean: Checks if the event is an exception event ($exception)fun isFatalExceptionEvent(): Boolean: Checks if the event is a fatal exception event ($exception) and properties ($exception_level=fatal)
PostHogEventName
Properties
val event: String: The event name sent to PostHog.
Entries
SNAPSHOT: Session replay snapshot event.SET: Sets person properties.IDENTIFY: Identifies a user.SCREEN: A screen view.GROUP_IDENTIFY: Sets group properties.CREATE_ALIAS: Aliases one distinct ID to another.FEATURE_FLAG_CALLED: A feature flag was evaluated.FEATURE_VIEW: A feature was viewed.FEATURE_INTERACTION: A feature was interacted with.EXCEPTION: A captured exception.
PostHogExceptionStepsConfig
Configuration for exception steps: breadcrumb-style context records that are attached to every captured $exception event as $exception_steps.
Record steps with com.posthog.PostHog.addExceptionStep.
Properties
var enabled: Boolean: Enable recording and attaching exception steps.var maxBytes: Int: Total UTF-8 byte budget for the rolling step buffer. When adding a step would exceed the budget, the oldest steps are evicted until the total fits. A single step larger than the budget is rejected outright.
PostHogIntegration
Integration interface for capturing events automatically or adding plugins to the PostHog SDK
Inheritors
PostHogErrorTrackingAutoCaptureIntegration:
Functions
fun install(postHog: PostHogInterface): Install the Integration after the SDK is setup that requires a posthog instance to capture eventsfun onChange(): Invalidates pending observations when identity, consent, screen, session or close state changes. Called synchronously on the caller's thread; calls may be nested or concurrent. This is a one-shot notification, not a pause/resume boundary. Uninstall must independently clean up.fun onRemoteConfig(loaded: Boolean = true): Called when the remote config attempt for the current identity resolves. Each integration is responsible for enabling or disabling features based on the state of the remote config.fun uninstall(): Uninstall the Integration after the SDK is closed
PostHogLogRecord
A captured log entry queued for delivery to PostHog's logs ingestion.
You don't construct these directly under normal use — call com.posthog.PostHog.logger methods instead. The record is surfaced as the input to PostHogBeforeSendLog hooks so you can inspect or rewrite it before it ships.
Properties
val appState: String? = null:"foreground"or"background"at capture time.val attributes: Map<String, Any>: Structured per-record attributes attached by the caller.val body: String: Log message body. Blank records are dropped afterbeforeSend.val distinctId: String? = null: Snapshot of the active PostHog distinct id at capture time.val featureFlagKeys: List<String>: Snapshot of feature flag keys that evaluated to active (truthy boolean or any multivariant value) at capture time. Use this to filter logs by flag state in the PostHog UI.val level: PostHogLogSeverity: Severity; defaults to PostHogLogSeverity.INFO.val observedTimeUnixNano: String: Advanced/observability field. Defaults to timeUnixNano; differs only when the SDK observes a record after the original timestamp (e.g. replay from persisted storage).val screenName: String? = null: Last screen name reported via com.posthog.PostHog.screen.val sessionId: String? = null: Snapshot of the active session id at capture time.val spanId: String? = null: W3C span id paired with traceId.val timeUnixNano: String: Advanced/observability field. Capture time as nanoseconds since epoch, encoded as a string to avoid i64 overflow on the JSON wire.val traceFlags: Int? = null: W3C trace flags byte (e.g.0x01for sampled).val traceId: String? = null: W3C trace id, when capture is part of a distributed trace.
PostHogLogSeverity
Severity level for a captured log record.
Constants are declared in severity order so >= comparisons on severityNumber give the expected result — for example, "warn and worse" is severity.severityNumber >= PostHogLogSeverity.WARN.severityNumber.
Maps to OpenTelemetry severity numbers (TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21) for the OTLP wire format.
Usage
Properties
val severityNumber: Int: OTLPseverityNumber(1, 5, 9, 13, 17, 21).val severityText: String: OTLPseverityText(lower-case).
Entries
TRACE: Fine-grained tracing detail.DEBUG: Debugging detail.INFO: Normal operation.WARN: Something unexpected that is not an error.ERROR: An error.FATAL: An unrecoverable error.
PostHogLogger
Captures application log records and forwards them to PostHog's logs ingestion endpoint.
Obtain via com.posthog.PostHog.logger (static, recommended) or com.posthog.PostHogInterface.logger when you hold a live SDK instance.
Kotlin usage
Java usage
Attribute values
Attribute values must be JSON-serializable: String, Number, Boolean, Date, or lists / maps composed of those types. Custom types without a registered serializer may fail to serialize at flush time — stick to the documented types.
Nested maps and lists are supported. The attributes map is deep-copied at capture time, so you can safely mutate the map (and any nested collections) after the call returns.
Drop / redact records
Register a PostHogBeforeSendLog via PostHogLogsConfig.addBeforeSend to drop or redact records before they are enqueued.
See also
PostHogLogSeverity:PostHogLogsConfig:PostHogBeforeSendLog:
Functions
fun debug(message: String, attributes: Map<String, Any>? = null): Captures a debug-level record. Diagnostic detail useful during development.fun error(message: String, attributes: Map<String, Any>? = null): Captures an error-level record. An operation failed; the app may continue.fun fatal(message: String, attributes: Map<String, Any>? = null): Captures a fatal-level record. An unrecoverable failure; the app likely cannot continue. Logged records still ship asynchronously, so consider calling com.posthog.PostHog.flush before the process exits.fun info(message: String, attributes: Map<String, Any>? = null): Captures an info-level record. Default level for regular runtime events.fun log(message: String, severity: PostHogLogSeverity = PostHogLogSeverity.INFO, attributes: Map<String, Any>? = null): Captures a log record at the given severity.fun trace(message: String, attributes: Map<String, Any>? = null): Captures a finest-grained trace-level record. Usually only enabled while diagnosing — high-volume; will trip the PostHogLogsConfig.rateCapMaxLogs cap quickly in production.fun warn(message: String, attributes: Map<String, Any>? = null): Captures a warn-level record. Something unexpected happened but the operation continued.
PostHogLogsConfig
Configuration for PostHog's logs ingestion.
Mutate fields on the PostHogConfig.logs property before calling PostHog.setup(config) — most knobs are snapshotted at setup and later changes are ignored. Per-field mutability is documented on each property.
Kotlin
Java
Properties
val beforeSendList: List<PostHogBeforeSendLog>: Snapshot of the currently registeredbeforeSendhooks, in registration order. Useful for diagnostics and test assertions; the returned list is an immutable copy.var environment: String?: Environment the app is running in. Lets you separate production logs from staging/development noise in the PostHog UI. Common values:"production","staging","development". Omitted from the payload entirely whennull.var flushAt: Int: Threshold at which the queue triggers a flush automatically.var flushIntervalSeconds: Int: How often the queue checks for records to flush, in seconds.var maxBatchSize: Int: Initial maximum number of records sent in a single request.var maxBufferSize: Int: Maximum number of records held on disk before the oldest is dropped (FIFO).var rateCapMaxLogs: Int: Maximum number of log records accepted per rateCapWindowSeconds before subsequent records in the same window are dropped at capture time.var rateCapWindowSeconds: Int: Tumbling window in seconds used by rateCapMaxLogs. The counter resets when wall-clock time advances past the window. Set to0(or any non-positive value) to disable the cap entirely.var resourceAttributes: Map<String, Any>: Additional metadata attached to every batch of records — anything you'd want to filter or segment by in the PostHog UI that isn't record-specific (e.g. region, build flavor, device model).var serviceName: String?: Name of the application sending logs. Used to group records in the PostHog UI when multiple apps report to the same project, and to match values used by other observability tooling.var serviceVersion: String?: Version of the application sending logs, typically your release version string. Lets you filter and segment log records by app version in the PostHog UI.
Functions
fun addBeforeSend(hook: PostHogBeforeSendLog): Adds abeforeSendhook that can mutate or drop log records before they reach the queue.fun removeBeforeSend(hook: PostHogBeforeSendLog): Removes a previously-addedbeforeSendhook. Pass the same lambda reference you originally registered.
PostHogMaskModifier
Jetpack Compose modifiers for controlling masking in Android session replay captures.
Functions
fun Modifier.postHogMask(isEnabled: Boolean = true): Modifier: Modifier to mask elements in the session replay.fun Modifier.postHogUnmask(isEnabled: Boolean = true): Modifier: Modifier to explicitly unmask elements in the session replay.
PostHogNextSurveyQuestion
Represents the next state after a user responds to a survey question.
Properties
val isSurveyCompleted: Boolean = false: Whether all questions have been answered and the survey is complete. Depending on the survey appearance configuration, you may want to show the "Thank you" message or dismiss the survey at this pointval questionIndex: Int: The index of the next question to be displayed (0-based)
PostHogOkHttpInterceptor
Interceptor that captures network telemetry for session replay and, when PostHogConfig.tracingHeaders is configured, injects PostHog tracing headers into matching OkHttp requests.
Install this interceptor on each okhttp3.OkHttpClient whose requests should be captured or annotated with tracing headers.
Parameters
captureNetworkTelemetry: Whether to capture network timing telemetry for session replay.postHog: Optional SDK instance to use; when omitted, the global PostHog singleton is used.
Functions
fun intercept(chain: Interceptor.Chain): Response
PostHogOnFeatureFlags
Interface for being notified once feature flags has been loaded
Functions
fun loaded(): The method that is called when feature flags are loaded
PostHogPropertiesSanitizer
Hook to sanitize the event properties
Functions
fun sanitize(properties: MutableMap<String, Any>): Map<String, Any>: Sanitizes the event properties
PostHogScreenshotColorMode
Pixel format for session replay screenshot captures, independent of resolution and compression.
Entries
ARGB_8888: Four bytes per pixel, preserving alpha and eight bits per color channel before encoding.RGB_565: Two bytes per pixel, with reduced color precision and no alpha channel.
PostHogSessionReplayConfig
Android session replay capture options.
Use this as PostHogAndroidConfig.sessionReplayConfig when enabling session replay through PostHogConfig.sessionReplay.
Properties
var captureLogcat: Boolean: Enable capturing of logcat as console events Defaults to truevar captureTouches: Boolean: Capture touch coordinates in session replay. Defaults to true. Set before SDK setup. Runtime changes are not supported. Screenshot and view capture are unaffected. Touches inside views markedph-no-captureorpostHogMask()nodes are never recorded. Disable this when other touch positions could reveal sensitive input, such as taps on fields masked only bymaskAllTextInputs.var debouncerDelayMs: Long: Debouncer delay used to reduce the number of snapshots captured and reduce performance impact. This is used for capturing the view as a wireframe or screenshot. The lower the number, the more snapshots are captured and the higher the performance impact. Defaults to 1000ms = 1s. Ps: it was 500ms by default until version 3.8.2.var drawableConverter: PostHogDrawableConverter?: Converts custom Drawable to Bitmap By default PostHog tries to convert the Drawable to Bitmap, the supported types are BitmapDrawable, ColorDrawable, GradientDrawable, InsetDrawable, LayerDrawable, RippleDrawablevar maskAllImages: Boolean: Enable masking of all images to a placeholder Defaults to truevar maskAllTextInputs: Boolean: Enable masking of all text and text input fields Defaults to truevar sampleRate: Double?: Local sample rate for session recording, a value between 0.0 and 1.0. When set, this takes precedence over the remote config sample rate.nullmeans no local override, so the SDK uses the remote config value. Defaults tonull.var screenshot: Boolean: By default Session replay will capture all the views on the screen as a wireframe, By enabling this option, PostHog will capture the screenshot of the screen. The screenshot may contain sensitive information, use with caution. In both modes, windows that setFLAG_SECUREare recorded as a solid black frame, and their touches are not recorded.@Volatilevar screenshotColorMode: PostHogScreenshotColorMode: Pixel format used for screenshot captures. Defaults to PostHogScreenshotColorMode.ARGB_8888 to preserve alpha and color precision before lossy WebP compression. PostHogScreenshotColorMode.RGB_565 uses less bitmap memory but reduces color precision and removes alpha, making transparent activity window regions appear black. In composed scenes, dialogs use ARGB_8888 to preserve transparency. Devices that reject RGB_565 fall back to ARGB_8888. Does not enable screenshot capture.@Volatilevar screenshotCompressionQuality: Int: WebP compression quality for screenshots, clamped to 0..100. Defaults to 30. Higher values generally retain more detail and produce larger payloads. Compression is lossy, except on Android 10 (API 29), where the platform's legacy WebP encoder uses lossless compression at quality 100. Does not change screenshot resolution or enable screenshot capture.@Volatilevar screenshotScale: Float?: Multiplier for the physical width and height of screenshot captures, clamped to 0.1..1.0.null(default) captures one pixel per dp (1/density), so screens with a density of 1 or less capture at full resolution. For example, 0.5 captures half the width and height. Dimensions are rounded up to at least one pixel; the logical replay viewport is unchanged. NaN and infinite values reset the scale tonull. Does not change compression quality, color mode, or enable screenshot capture.var throttleDelayMs: Long: Throttling delay used to reduce the number of snapshots captured and reduce performance impact. This is used for capturing the view as a wireframe or screenshot. The lower the number, the more snapshots are captured and the higher the performance impact. Defaults to 1000ms = 1s.var verifyScreenshotMaskAlignment: Boolean: Verifies mask alignment for session replay screenshots. This can preserve screenshots during pixel-only redraws, including continuously animated content, but performs additional view hierarchy walks while a screenshot is captured. Defaults to false. Windows with a Compose root always use the verified path regardless of this flag, so setting it to false does not disable verification for them.
PostHogSurveyResponse
Represents a user's response to a survey question.
Inheritors
Text:SingleChoice:MultipleChoice:Rating:Link:
Functions
fun toResponseValue(): Any?: Creates a response value for sending to the PostHog API.
PostHogSurveysConfig
Configuration for PostHog Surveys feature.
Properties
var overrideDisplayLanguage: String?: Optional explicit override for the language used when rendering surveys.var surveysDelegate: PostHogSurveysDelegate: Delegate responsible for managing survey presentation in your app. Handles survey rendering, response collection, and lifecycle events. You can provide your own delegate for a custom survey presentation.
PostHogSurveysDefaultDelegate
Default implementation of PostHogSurveysDelegate. This implementation doesn't render any UI, it only logs when survey methods are called.
Users should implement their own delegate to handle survey rendering.
Functions
fun cleanupSurveys(): Called when surveys should be cleaned up. This default implementation only logs that cleanup was requested.fun renderSurvey(survey: PostHogDisplaySurvey, onSurveyShown: OnPostHogSurveyShown, onSurveyResponse: OnPostHogSurveyResponse, onSurveyClosed: OnPostHogSurveyClosed): Called when a survey should be rendered. This default implementation only logs that a survey was requested to be shown.
PostHogSurveysDelegate
Delegate responsible for managing survey presentation in your app. Handles survey rendering, response collection, and lifecycle events. You can provide your own delegate for a custom survey presentation.
Inheritors
PostHogSurveysDefaultDelegate:PostHogSurveysResumeAwareDelegate:
Functions
fun cleanupSurveys(): Called when surveys are stopped to clean up any UI elements and reset the survey display state. This method should handle the dismissal of any active surveys and cleanup of associated resources.fun renderSurvey(survey: PostHogDisplaySurvey, onSurveyShown: OnPostHogSurveyShown, onSurveyResponse: OnPostHogSurveyResponse, onSurveyClosed: OnPostHogSurveyClosed): Called when an activated PostHog survey needs to be rendered on the app's UI
PostHogSurveysResumeAwareDelegate
Optional capability for delegates that restore unfinished surveys.
Delegates without this capability, or returning false, start fresh at question 0. Opting in requires starting at PostHogDisplaySurvey.initialQuestionIndex; the SDK restores saved answers and the submission ID for that attempt.
For example, a renderer that honors the initial question can declare: override val supportsSurveyResume: Boolean = true.
Properties
val supportsSurveyResume: Boolean: Whether this delegate honors PostHogDisplaySurvey.initialQuestionIndex, so the SDK resumes surveys.
Functions
fun cleanupSurveys(): Called when surveys are stopped to clean up any UI elements and reset the survey display state. This method should handle the dismissal of any active surveys and cleanup of associated resources.fun renderSurvey(survey: PostHogDisplaySurvey, onSurveyShown: OnPostHogSurveyShown, onSurveyResponse: OnPostHogSurveyResponse, onSurveyClosed: OnPostHogSurveyClosed): Called when an activated PostHog survey needs to be rendered on the app's UI
RatingSurveyQuestion
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval display: SurveyRatingDisplayType?val id: String? = nullval lowerBoundLabel: String?val optional: Boolean? = nullval question: String? = nullval scale: Int?val skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = nullval upperBoundLabel: String?
SingleSurveyQuestion
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval choices: List<String>?val description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval hasOpenChoice: Boolean?val id: String? = nullval optional: Boolean? = nullval question: String? = nullval shuffleOptions: Boolean?val skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = null
Survey
Properties
val appearance: SurveyAppearance?val conditions: SurveyConditions?@SerializedName(value = "current_iteration")val currentIteration: Int?@SerializedName(value = "current_iteration_start_date")val currentIterationStartDate: Date?val description: String?@SerializedName(value = "enable_partial_responses")val enablePartialResponses: Boolean? = null@SerializedName(value = "end_date")val endDate: Date?@SerializedName(value = "feature_flag_keys")val featureFlagKeys: List<SurveyFeatureFlagKeyValue>?val id: String@SerializedName(value = "internal_targeting_flag_key")val internalTargetingFlagKey: String?@SerializedName(value = "linked_flag_key")val linkedFlagKey: String?val questions: List<SurveyQuestion>val schedule: SurveySchedule?@SerializedName(value = "start_date")val startDate: Date?@SerializedName(value = "targeting_flag_key")val targetingFlagKey: String?val translations: Map<String, SurveyTranslation>? = nullval type: SurveyType
SurveyAppearance
Properties
val autoDisappear: Boolean?val backgroundColor: String?val borderColor: Stringval descriptionTextColor: String?val displayIntroScreen: Boolean? = nullval displayThankYouMessage: Boolean?val fontFamily: String?val inputBackground: String?val inputTextColor: String?val introScreenButtonText: String? = nullval introScreenDescription: String? = nullval introScreenDescriptionContentType: SurveyTextContentType? = nullval introScreenHeader: String? = nullval placeholder: String?val position: SurveyAppearancePosition?val ratingButtonActiveColor: String?val ratingButtonColor: String?val ratingButtonHoverColor: String?val shuffleQuestions: Boolean?val submitButtonColor: String?val submitButtonText: String?val submitButtonTextColor: String?val surveyPopupDelaySeconds: Double?val textColor: String?val thankYouMessageCloseButtonText: String?val thankYouMessageDescription: String?val thankYouMessageDescriptionContentType: SurveyTextContentType?val thankYouMessageHeader: String?val whiteLabel: Boolean?val widgetColor: String?val widgetLabel: String?val widgetSelector: String?val widgetType: SurveyAppearanceWidgetType?
SurveyAppearancePosition
Properties
val value: String
Entries
LEFTRIGHTCENTER
SurveyAppearanceWidgetType
Properties
val value: String
Entries
BUTTONTABSELECTOR
SurveyConditions
Properties
val deviceTypes: List<String>?val deviceTypesMatchType: SurveyMatchType?val events: SurveyEventConditions?val linkedFlagVariant: String? = null: Required variant of the linked flag; "any" accepts any enabled value.val seenSurveyWaitPeriodInDays: Int?val selector: String?val url: String?val urlMatchType: SurveyMatchType?
SurveyEventCondition
Properties
val propertyFilters: Map<String, SurveyPropertyFilter>? = null
SurveyEventConditions
Properties
val repeatedActivation: Boolean?
SurveyFeatureFlagKeyValue
Properties
val key: Stringval value: String?
SurveyMatchType
Properties
val value: String
Entries
REGEXNOT_REGEXEXACTIS_NOTI_CONTAINSNOT_I_CONTAINSGTLT
SurveyPropertyFilter
Properties
val operator: SurveyMatchType
SurveyQuestion
Inheritors
OpenSurveyQuestion:LinkSurveyQuestion:RatingSurveyQuestion:SingleSurveyQuestion:MultipleSurveyQuestion:
Properties
val branching: SurveyQuestionBranching? = nullval buttonText: String? = nullval description: String? = nullval descriptionContentType: SurveyTextContentType? = nullval id: String? = nullval optional: Boolean? = nullval question: String? = nullval skipSubmitButton: Boolean? = nullval translations: Map<String, SurveyQuestionTranslation>? = nullval type: SurveyQuestionType? = null
SurveyQuestionBranching
Inheritors
Next:End:ResponseBased:SpecificQuestion:
SurveyQuestionBranchingType
Properties
val value: String
Entries
NEXT_QUESTIONENDRESPONSE_BASEDSPECIFIC_QUESTION
SurveyQuestionTranslation
Localized overrides for a survey question.
Fields are a superset across question types: link only applies to link questions, lowerBoundLabel / upperBoundLabel only to rating questions, and choices only to single/multiple choice questions. Irrelevant fields are ignored for other types.
Properties
val buttonText: String? = nullval choices: List<String>? = nullval description: String? = nullval link: String? = nullval lowerBoundLabel: String? = nullval question: String? = nullval upperBoundLabel: String? = null
SurveyQuestionType
Properties
val value: String
Entries
OPENLINKRATINGMULTIPLE_CHOICESINGLE_CHOICE
SurveyRatingDisplayType
Properties
val value: String
Entries
NUMBEREMOJI
SurveySchedule
Properties
val value: String
Entries
ONCERECURRINGALWAYS
SurveyTextContentType
Properties
val value: String
Entries
HTMLTEXT
SurveyTranslation
Localized overrides for a survey, keyed by language code (e.g. "fr", "pt-BR").
The survey-level description is intentionally NOT translatable — it is only used for internal previews and never rendered to end users.
Properties
val introScreenButtonText: String? = nullval introScreenDescription: String? = nullval introScreenHeader: String? = nullval thankYouMessageCloseButtonText: String? = nullval thankYouMessageDescription: String? = nullval thankYouMessageHeader: String? = null
SurveyType
Properties
val value: String
Entries
POPOVERAPIWIDGET





