diff --git a/.changeset/public-kdocs-shine.md b/.changeset/public-kdocs-shine.md new file mode 100644 index 000000000..2f46b363d --- /dev/null +++ b/.changeset/public-kdocs-shine.md @@ -0,0 +1,7 @@ +--- +"posthog": patch +"posthog-android": patch +"posthog-server": patch +--- + +Improve public API KDoc coverage. diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt index 937c2d878..7718fd778 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt @@ -29,19 +29,20 @@ import com.posthog.vendor.uuid.TimeBasedEpochGenerator import java.io.File /** - * Main entrypoint for the Android SDK - * Use the setup method to set a global and singleton instance - * Or use the with method that returns an instance that you can hold and pass it around + * Main entry point for the Android SDK. + * + * Use [setup] to configure the process-wide singleton, or [with] to create an instance that you + * hold and pass around. */ public class PostHogAndroid private constructor() { public companion object { private val lock = Any() /** - * Setup the SDK and set a global and singleton instance - * @param T the type of the Config - * @property context the Context - * @property config the Config + * Sets up the SDK and stores it as the global singleton. + * + * @param context Android context; the application context is retained internally. + * @param config Android SDK configuration. */ public fun setup( context: Context, @@ -55,16 +56,15 @@ public class PostHogAndroid private constructor() { } /** - * Setup the SDK and returns an instance that you can hold and pass it around + * Creates and returns a configured SDK instance that you can hold and pass around. * - * All default PostHogIntegration's will only be installed for the very 1st instance, - * either that be created with the [setup] or [with] method otherwise they would race each other - * and cause issues, so the 1st instance of the SDK that is created on the hosting app - * will hold all installed integrations, the order of the setup matters. + * 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. * - * @param T the type of the Config - * @property context the Context - * @property config the Config + * @param context Android context; the application context is retained internally. + * @param config Android SDK configuration. + * @return The configured PostHog client instance. */ public fun with( context: Context, diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt index 4a13eb95c..86c913bf9 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt @@ -8,15 +8,19 @@ import com.posthog.internal.PostHogApiEndpoint import com.posthog.internal.PostHogQueue /** - * The SDK Config - * @property apiKey the PostHog API Key - * @property captureApplicationLifecycleEvents captures lifecycle events such as app installed, app updated, app opened and backgrounded - * @property captureDeepLinks captures deep links events - * @property captureScreenViews automatically captures a `$screen` event whenever a foreground - * Activity starts (via `ActivityLifecycleCallbacks.onActivityStarted`). When enabled, the most - * recent screen name is also attached as `$screen_name` to every subsequent event captured by - * the SDK. To opt out of `$screen_name` stamping entirely, set to `false` AND avoid calling - * `PostHog.screen(...)` manually. Default: `true`. + * Android SDK configuration. + * + * @param apiKey PostHog project API key. Leading and trailing whitespace is trimmed. + * @param host PostHog ingestion host. Defaults to [DEFAULT_HOST]. + * @property captureApplicationLifecycleEvents Whether to capture application lifecycle events + * automatically, including app installed, app updated, app opened, and app backgrounded. + * @property captureDeepLinks Whether to capture `Deep Link Opened` events automatically. + * @property captureScreenViews Whether to capture a `$screen` event whenever a foreground + * Activity starts (via `ActivityLifecycleCallbacks.onActivityStarted`). When enabled, the most + * recent screen name is also attached as `$screen_name` to every subsequent event captured by + * the SDK. To opt out of `$screen_name` stamping entirely, set this to `false` and avoid calling + * `PostHog.screen(...)` manually. Default: `true`. + * @property sessionReplayConfig Android-specific session replay capture options. */ public open class PostHogAndroidConfig @JvmOverloads diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt index 9335de787..7f6a30aa1 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt @@ -3,6 +3,16 @@ package com.posthog.android.replay import android.graphics.Bitmap import android.graphics.drawable.Drawable +/** + * Converts Android [Drawable] instances that the SDK cannot render by default into [Bitmap]s for + * session replay screenshots or wireframes. + */ public fun interface PostHogDrawableConverter { + /** + * Converts [drawable] to a bitmap representation. + * + * @param drawable Drawable to convert. + * @return A bitmap to capture, or `null` when this converter cannot handle the drawable. + */ public fun convert(drawable: Drawable): Bitmap? } diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogMaskModifier.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogMaskModifier.kt index a4a9d14b5..c385c3d97 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogMaskModifier.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogMaskModifier.kt @@ -6,16 +6,21 @@ import androidx.compose.ui.semantics.semantics import com.posthog.android.replay.PostHogReplayIntegration.Companion.PH_NO_CAPTURE_LABEL import com.posthog.android.replay.PostHogReplayIntegration.Companion.PH_NO_MASK_LABEL +/** + * Jetpack Compose modifiers for controlling masking in Android session replay captures. + */ public object PostHogMaskModifier { internal val PostHogReplayMask = SemanticsPropertyKey(PH_NO_CAPTURE_LABEL) internal val PostHogReplayUnmask = SemanticsPropertyKey(PH_NO_MASK_LABEL) /** * Modifier to mask elements in the session replay. - * @param isEnabled If true, the modifier takes effect and the element will be masked in the session replay. - * If false, the modifier has no effect, as if it was never applied. - * This is useful for controlling masking dynamically via a global setting or remote config - * without having to add or remove the modifier from the composable tree. + * + * @param isEnabled If true, the modifier takes effect and the element will be masked in the + * session replay. If false, the modifier has no effect, as if it was never applied. This is + * useful for controlling masking dynamically via a global setting or remote config without + * having to add or remove the modifier from the composable tree. + * @return A [Modifier] with PostHog masking semantics applied. */ public fun Modifier.postHogMask(isEnabled: Boolean = true): Modifier { return semantics( @@ -27,12 +32,16 @@ public object PostHogMaskModifier { /** * Modifier to explicitly unmask elements in the session replay. - * When applied, the element will NOT be masked even if maskAllTextInputs or maskAllImages is enabled. - * This modifier takes precedence over the global masking configuration and [postHogMask]. - * @param isEnabled If true, the modifier takes effect and the element will not be masked in the session replay. - * If false, the modifier has no effect, as if it was never applied. - * This is useful for controlling unmasking dynamically via a global setting or remote config - * without having to add or remove the modifier from the composable tree. + * + * When applied, the element will not be masked even if `maskAllTextInputs` or `maskAllImages` + * is enabled. This modifier takes precedence over the global masking configuration and + * [postHogMask]. + * + * @param isEnabled If true, the modifier takes effect and the element will not be masked in the + * session replay. If false, the modifier has no effect, as if it was never applied. This is + * useful for controlling unmasking dynamically via a global setting or remote config without + * having to add or remove the modifier from the composable tree. + * @return A [Modifier] with PostHog unmasking semantics applied. */ public fun Modifier.postHogUnmask(isEnabled: Boolean = true): Modifier { return semantics( diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt index 3a0c36fb5..ff5be7d3c 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt @@ -1,5 +1,11 @@ package com.posthog.android.replay +/** + * Android session replay capture options. + * + * Use this as `PostHogAndroidConfig.sessionReplayConfig` when enabling session replay through + * `PostHogConfig.sessionReplay`. + */ public class PostHogSessionReplayConfig @JvmOverloads constructor( @@ -31,27 +37,26 @@ public class PostHogSessionReplayConfig */ public var screenshot: Boolean = false, /** - * Deboucer 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 more snapshots will be captured but higher the performance impact - * Defaults to 1000ms = 1s - * Ps: it was 500ms by default until version 3.8.2 + * 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. */ @Deprecated("Use throttleDelayMs instead") public var debouncerDelayMs: Long = 1000, /** - * 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 more snapshots will be captured but higher the performance impact - * Defaults to 1000ms = 1s + * 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. */ public var throttleDelayMs: Long = 1000, /** * 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. - * null means no local override (use the remote config value). - * This is a convenience property that sets PostHogConfig.sampleRate. - * Defaults to null + * `null` means no local override, so the SDK uses the remote config value. + * Defaults to `null`. */ public var sampleRate: Double? = null, ) { diff --git a/posthog-server/src/main/java/com/posthog/server/PostHog.kt b/posthog-server/src/main/java/com/posthog/server/PostHog.kt index 7bd692f8a..2af98c845 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHog.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHog.kt @@ -344,9 +344,10 @@ public class PostHog : PostHogStateless(), PostHogInterface { public companion object { /** - * Set up the SDK and returns an instance that you can hold and pass it around - * @param T the type of the Config - * @property config the Config + * Sets up the SDK and returns an instance that you can hold and pass around. + * + * @param config Server SDK configuration. + * @return The configured PostHog client instance. */ @JvmStatic public fun with(config: T): PostHogInterface { diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogCaptureOptions.kt b/posthog-server/src/main/java/com/posthog/server/PostHogCaptureOptions.kt index b1b2ea419..75a675e52 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogCaptureOptions.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogCaptureOptions.kt @@ -4,8 +4,19 @@ import java.time.Instant import java.util.Date /** - * Provides an ergonomic interface when providing options for capturing events - * This is mainly meant to be used from Java, as Kotlin can use named parameters. + * Java-friendly options for capturing events. + * + * Kotlin callers can usually use named parameters on [PostHogInterface.capture] instead. + * + * @property properties Custom event properties. + * @property userProperties Person properties to set as `$set` with the capture. + * @property userPropertiesSetOnce Person properties to set as `$set_once` with the capture. + * @property groups Group assignments to attach as `$groups`. + * @property timestamp Event timestamp. When null, the SDK uses the current time. + * @property appendFeatureFlags Whether to enrich the event by evaluating and attaching feature flag + * properties. Prefer passing a pre-evaluated [flags] snapshot for new code. + * @property flags Optional snapshot returned by [PostHogInterface.evaluateFlags] to attach feature + * flag properties without another `/flags` request. * @see Documentation: Capturing events */ public class PostHogCaptureOptions private constructor( @@ -17,17 +28,37 @@ public class PostHogCaptureOptions private constructor( public val appendFeatureFlags: Boolean = false, public val flags: PostHogFeatureFlagEvaluations? = null, ) { + /** + * Mutable builder for [PostHogCaptureOptions]. + */ public class Builder { + /** Custom event properties accumulated for the capture. */ public var properties: MutableMap? = null + + /** Person properties to set as `$set`. */ public var userProperties: MutableMap? = null + + /** Person properties to set as `$set_once`. */ public var userPropertiesSetOnce: MutableMap? = null + + /** Group assignments to attach as `$groups`. */ public var groups: MutableMap? = null + + /** Event timestamp override. */ public var timestamp: Date? = null + + /** Whether to evaluate and append feature flag properties during capture. */ public var appendFeatureFlags: Boolean = false + + /** Optional pre-evaluated feature flag snapshot to append during capture. */ public var flags: PostHogFeatureFlagEvaluations? = null /** - * Add a single custom property to the capture options + * Add a single custom property to the capture options. + * + * @param key Property name. + * @param value Property value. + * @return This builder. */ public fun property( key: String, @@ -41,7 +72,10 @@ public class PostHogCaptureOptions private constructor( } /** - * Appends multiple custom properties to the capture options + * Appends multiple custom properties to the capture options. + * + * @param properties Properties to merge into the capture options. + * @return This builder. */ public fun properties(properties: Map): Builder { this.properties = @@ -52,7 +86,11 @@ public class PostHogCaptureOptions private constructor( } /** - * Adds a single user property to the capture options + * Adds a single user property to the capture options. + * + * @param key User property name. + * @param value User property value. + * @return This builder. * @see Documentation: User Properties */ public fun userProperty( @@ -68,6 +106,9 @@ public class PostHogCaptureOptions private constructor( /** * Appends multiple user properties to the capture options. + * + * @param userProperties User properties to merge. + * @return This builder. * @see Documentation: User Properties */ public fun userProperties(userProperties: Map): Builder { @@ -80,6 +121,10 @@ public class PostHogCaptureOptions private constructor( /** * Adds a single user property (set once) to the capture options. + * + * @param key User property name. + * @param value User property value. + * @return This builder. * @see Documentation: User Properties */ public fun userPropertySetOnce( @@ -95,6 +140,9 @@ public class PostHogCaptureOptions private constructor( /** * Appends multiple user properties (set once) to the capture options. + * + * @param userPropertiesSetOnce User properties to merge as `$set_once`. + * @return This builder. * @see Documentation: User Properties */ public fun userPropertiesSetOnce(userPropertiesSetOnce: Map): Builder { @@ -107,6 +155,10 @@ public class PostHogCaptureOptions private constructor( /** * Adds a single group to the capture options. + * + * @param type Group type, for example `company`. + * @param key Group key or identifier. + * @return This builder. * @see Documentation: Group Analytics */ public fun group( @@ -122,6 +174,9 @@ public class PostHogCaptureOptions private constructor( /** * Appends multiple groups to the capture options. + * + * @param groups Groups to merge, keyed by group type. + * @return This builder. * @see Documentation: Group Analytics */ public fun groups(groups: Map): Builder { @@ -134,6 +189,9 @@ public class PostHogCaptureOptions private constructor( /** * Override the timestamp for the event. + * + * @param date Event timestamp. + * @return This builder. * @see Documentation: Timestamps */ public fun timestamp(date: Date): Builder { @@ -143,6 +201,9 @@ public class PostHogCaptureOptions private constructor( /** * Override the timestamp for the event. + * + * @param epochMillis Event timestamp in milliseconds since the Unix epoch. + * @return This builder. * @see Documentation: Timestamps */ public fun timestamp(epochMillis: Long): Builder { @@ -152,6 +213,9 @@ public class PostHogCaptureOptions private constructor( /** * Override the timestamp for the event. + * + * @param instant Event timestamp. + * @return This builder. * @see Documentation: Timestamps */ public fun timestamp(instant: Instant): Builder { @@ -161,8 +225,13 @@ public class PostHogCaptureOptions private constructor( /** * When true, enriches the event with all evaluated feature flags. - * Adds `$feature/{flagName}` properties for each flag and - * `$active_feature_flags` array containing names of all truthy flags. + * + * Adds `$feature/{flagName}` properties for each flag and `$active_feature_flags` array + * containing names of all truthy flags. Prefer evaluating flags once and passing [flags] + * when you need to attach flag information to a capture. + * + * @param appendFeatureFlags Whether to evaluate and attach feature flag properties. + * @return This builder. * @see Documentation: Feature Flags */ public fun appendFeatureFlags(appendFeatureFlags: Boolean): Builder { @@ -171,16 +240,25 @@ public class PostHogCaptureOptions private constructor( } /** - * Attach a snapshot returned by [PostHogInterface.evaluateFlags]. The capture event will be - * enriched with `$feature/` properties and `$active_feature_flags` from the snapshot - * without making another `/flags` request. Mutually exclusive with [appendFeatureFlags]; - * the snapshot wins when both are supplied. + * Attach a snapshot returned by [PostHogInterface.evaluateFlags]. + * + * The capture event will be enriched with `$feature/` properties and + * `$active_feature_flags` from the snapshot without making another `/flags` request. + * Mutually exclusive with [appendFeatureFlags]; the snapshot wins when both are supplied. + * + * @param flags Pre-evaluated feature flag snapshot, or null to clear it. + * @return This builder. */ public fun flags(flags: PostHogFeatureFlagEvaluations?): Builder { this.flags = flags return this } + /** + * Builds an immutable [PostHogCaptureOptions] instance. + * + * @return Capture options containing the accumulated values. + */ public fun build(): PostHogCaptureOptions = PostHogCaptureOptions( properties, @@ -194,6 +272,11 @@ public class PostHogCaptureOptions private constructor( } public companion object { + /** + * Creates a new Java-friendly capture options builder. + * + * @return A new [Builder]. + */ @JvmStatic public fun builder(): Builder = Builder() } diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt index 53ade041b..7e44105ef 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt @@ -12,11 +12,13 @@ import com.posthog.server.internal.PostHogServerContext import java.net.Proxy /** - * The SDK Config + * Server-side SDK configuration. + * + * Create instances directly in Kotlin, or use [builder] from Java. */ public open class PostHogConfig constructor( /** - * The PostHog API Key + * The PostHog project API key. */ apiKey: String, /** @@ -88,8 +90,8 @@ public open class PostHogConfig constructor( */ public var onFeatureFlags: PostHogOnFeatureFlags? = null, /** - * Hook that allows to sanitize the event properties - * The hook is called before the event is cached or sent over the wire + * Optional HTTP proxy for requests to the PostHog API. + * Defaults to null. */ public var proxy: Proxy? = null, /** @@ -139,7 +141,7 @@ public open class PostHogConfig constructor( public var evaluationContexts: List? = null, ) { /** - * The PostHog API Key + * The PostHog project API key, trimmed of leading and trailing whitespace. */ public val apiKey: String = apiKey.trim() @@ -160,14 +162,29 @@ public open class PostHogConfig constructor( private val beforeSendCallbacks = mutableListOf() private val integrations = mutableListOf() + /** + * Adds a before-send hook that can mutate or drop events before they are queued. + * + * @param beforeSend Hook to add. + */ public fun addBeforeSend(beforeSend: PostHogBeforeSend) { beforeSendCallbacks.add(beforeSend) } + /** + * Removes a previously added before-send hook. + * + * @param beforeSend Hook to remove. + */ public fun removeBeforeSend(beforeSend: PostHogBeforeSend) { beforeSendCallbacks.remove(beforeSend) } + /** + * Adds an integration to install when the SDK is set up. + * + * @param integration Integration to add. + */ public fun addIntegration(integration: PostHogIntegration) { integrations.add(integration) } @@ -241,10 +258,21 @@ public open class PostHogConfig constructor( public const val DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE: Int = 1000 public const val DEFAULT_POLL_INTERVAL_SECONDS: Int = 30 + /** + * Creates a Java-friendly builder. + * + * @param apiKey PostHog project API key. + * @return A new [Builder]. + */ @JvmStatic public fun builder(apiKey: String): Builder = Builder(apiKey) } + /** + * Java-friendly builder for [PostHogConfig]. + * + * @param apiKey PostHog project API key. + */ public class Builder(private val apiKey: String) { private var host: String = DEFAULT_HOST private var debug: Boolean = false @@ -268,14 +296,46 @@ public open class PostHogConfig constructor( private var pollIntervalSeconds: Int = DEFAULT_POLL_INTERVAL_SECONDS private var evaluationContexts: List? = null + /** + * Sets the PostHog ingestion host. + * + * @param host Host URL, usually [DEFAULT_US_HOST] or [DEFAULT_EU_HOST]. + * @return This builder. + */ public fun host(host: String): Builder = apply { this.host = host } + /** + * Enables or disables SDK debug logging. + * + * @param debug true to enable detailed SDK logs. + * @return This builder. + */ public fun debug(debug: Boolean): Builder = apply { this.debug = debug } + /** + * Sets whether feature flag lookups send `$feature_flag_called` events by default. + * + * @param sendFeatureFlagEvent true to send usage events automatically. + * @return This builder. + */ public fun sendFeatureFlagEvent(sendFeatureFlagEvent: Boolean): Builder = apply { this.sendFeatureFlagEvent = sendFeatureFlagEvent } + /** + * Sets whether feature flags are preloaded automatically during setup. + * + * @param preloadFeatureFlags true to preload feature flags. + * @return This builder. + */ public fun preloadFeatureFlags(preloadFeatureFlags: Boolean): Builder = apply { this.preloadFeatureFlags = preloadFeatureFlags } + /** + * Sets the remote config preload flag. + * + * This option is deprecated because remote config is always enabled. + * + * @param remoteConfig Deprecated no-op value. + * @return This builder. + */ @Deprecated( message = "Remote config is now always enabled. This option is a no-op and will be removed in a future version.", level = DeprecationLevel.WARNING, @@ -283,30 +343,105 @@ public open class PostHogConfig constructor( @Suppress("DEPRECATION") public fun remoteConfig(remoteConfig: Boolean): Builder = apply { this.remoteConfig = remoteConfig } + /** + * Sets how many events are queued before an automatic flush. + * + * @param flushAt Event count threshold. + * @return This builder. + */ public fun flushAt(flushAt: Int): Builder = apply { this.flushAt = flushAt } + /** + * Sets the maximum number of queued events kept in memory. + * + * @param maxQueueSize Maximum queued events. + * @return This builder. + */ public fun maxQueueSize(maxQueueSize: Int): Builder = apply { this.maxQueueSize = maxQueueSize } + /** + * Sets the maximum number of events sent in one batch request. + * + * @param maxBatchSize Maximum batch size. + * @return This builder. + */ public fun maxBatchSize(maxBatchSize: Int): Builder = apply { this.maxBatchSize = maxBatchSize } + /** + * Sets the periodic flush interval in seconds. + * + * @param flushIntervalSeconds Flush interval in seconds. + * @return This builder. + */ public fun flushIntervalSeconds(flushIntervalSeconds: Int): Builder = apply { this.flushIntervalSeconds = flushIntervalSeconds } + /** + * Sets custom event encryption hooks. + * + * @param encryption Encryption implementation, or null for no encryption. + * @return This builder. + */ public fun encryption(encryption: PostHogEncryption?): Builder = apply { this.encryption = encryption } + /** + * Sets the callback invoked when feature flags are loaded. + * + * @param onFeatureFlags Callback, or null for no callback. + * @return This builder. + */ public fun onFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?): Builder = apply { this.onFeatureFlags = onFeatureFlags } + /** + * Sets an HTTP proxy for PostHog API requests. + * + * @param proxy Proxy to use, or null for no proxy. + * @return This builder. + */ public fun proxy(proxy: Proxy?): Builder = apply { this.proxy = proxy } + /** + * Sets the maximum number of feature flag results cached in memory. + * + * @param featureFlagCacheSize Maximum cache entries. + * @return This builder. + */ public fun featureFlagCacheSize(featureFlagCacheSize: Int): Builder = apply { this.featureFlagCacheSize = featureFlagCacheSize } + /** + * Sets the maximum age of a cached feature flag result in milliseconds. + * + * @param featureFlagCacheMaxAgeMs Maximum cache age in milliseconds. + * @return This builder. + */ public fun featureFlagCacheMaxAgeMs(featureFlagCacheMaxAgeMs: Int): Builder = apply { this.featureFlagCacheMaxAgeMs = featureFlagCacheMaxAgeMs } + /** + * Sets the maximum number of distinct `$feature_flag_called` events tracked for deduplication. + * + * @param featureFlagCalledCacheSize Maximum deduplication cache entries. + * @return This builder. + */ public fun featureFlagCalledCacheSize(featureFlagCalledCacheSize: Int): Builder = apply { this.featureFlagCalledCacheSize = featureFlagCalledCacheSize } + /** + * Enables or disables local feature flag evaluation. + * + * @param localEvaluation true to periodically fetch definitions and evaluate flags locally. + * @return This builder. + */ public fun localEvaluation(localEvaluation: Boolean): Builder = apply { this.localEvaluation = localEvaluation } + /** + * Sets the personal API key used for local feature flag evaluation. + * + * Setting a non-blank personal API key automatically enables [localEvaluation] unless it has + * already been set explicitly. + * + * @param personalApiKey Personal API key, or null/blank to clear it. + * @return This builder. + */ public fun personalApiKey(personalApiKey: String?): Builder = apply { this.personalApiKey = personalApiKey?.trim()?.ifBlank { null } @@ -315,10 +450,27 @@ public open class PostHogConfig constructor( } } + /** + * Sets how often local evaluation flag definitions are polled. + * + * @param pollIntervalSeconds Poll interval in seconds. + * @return This builder. + */ public fun pollIntervalSeconds(pollIntervalSeconds: Int): Builder = apply { this.pollIntervalSeconds = pollIntervalSeconds } + /** + * Sets evaluation context tags that constrain which feature flags are evaluated. + * + * @param evaluationContexts Context tags, or null to evaluate all flags. + * @return This builder. + */ public fun evaluationContexts(evaluationContexts: List?): Builder = apply { this.evaluationContexts = evaluationContexts } + /** + * Builds a [PostHogConfig] from the accumulated values. + * + * @return The configured server SDK config. + */ @Suppress("DEPRECATION") public fun build(): PostHogConfig = PostHogConfig( diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogEvaluateFlagsOptions.kt b/posthog-server/src/main/java/com/posthog/server/PostHogEvaluateFlagsOptions.kt index 0a5fcf252..a8ecf116c 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogEvaluateFlagsOptions.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogEvaluateFlagsOptions.kt @@ -1,8 +1,16 @@ package com.posthog.server /** - * Java-friendly options builder for [PostHogInterface.evaluateFlags]. Kotlin callers should prefer - * named arguments on the method itself. + * Java-friendly options builder for [PostHogInterface.evaluateFlags]. + * + * Kotlin callers should prefer named arguments on the method itself. + * + * @property groups Groups for group-based flags, keyed by group type. + * @property personProperties Person properties to use for flag evaluation. + * @property groupProperties Group properties to use for flag evaluation, keyed by group type. + * @property flagKeys Optional list of flag keys to evaluate. When null, all matching flags are evaluated. + * @property onlyEvaluateLocally Whether to skip the remote `/flags` fallback if local evaluation is inconclusive. + * @property disableGeoip Whether to send `geoip_disable=true` during remote evaluation. */ public class PostHogEvaluateFlagsOptions private constructor( public val groups: Map?, @@ -12,14 +20,35 @@ public class PostHogEvaluateFlagsOptions private constructor( public val onlyEvaluateLocally: Boolean, public val disableGeoip: Boolean, ) { + /** + * Mutable builder for [PostHogEvaluateFlagsOptions]. + */ public class Builder { + /** Groups for group-based flags, keyed by group type. */ public var groups: MutableMap? = null + + /** Person properties used for flag evaluation. */ public var personProperties: MutableMap? = null + + /** Group properties used for flag evaluation, keyed by group type. */ public var groupProperties: MutableMap>? = null + + /** Flag keys to request from the server. */ public var flagKeys: MutableList? = null + + /** Whether to skip the remote fallback if local evaluation cannot resolve a flag. */ public var onlyEvaluateLocally: Boolean = false + + /** Whether to disable GeoIP property lookup for the remote evaluation request. */ public var disableGeoip: Boolean = false + /** + * Adds a single group for group-based flag evaluation. + * + * @param type Group type, for example `company`. + * @param key Group key or identifier. + * @return This builder. + */ public fun group( type: String, key: String, @@ -28,11 +57,24 @@ public class PostHogEvaluateFlagsOptions private constructor( return this } + /** + * Appends multiple groups for group-based flag evaluation. + * + * @param groups Groups to merge, keyed by group type. + * @return This builder. + */ public fun groups(groups: Map): Builder { this.groups = (this.groups ?: mutableMapOf()).apply { putAll(groups) } return this } + /** + * Adds a single person property for flag evaluation. + * + * @param key Person property name. + * @param value Person property value. + * @return This builder. + */ public fun personProperty( key: String, value: Any?, @@ -41,11 +83,25 @@ public class PostHogEvaluateFlagsOptions private constructor( return this } + /** + * Appends multiple person properties for flag evaluation. + * + * @param personProperties Person properties to merge. + * @return This builder. + */ public fun personProperties(personProperties: Map): Builder { this.personProperties = (this.personProperties ?: mutableMapOf()).apply { putAll(personProperties) } return this } + /** + * Adds a single group property for flag evaluation. + * + * @param type Group type, for example `company`. + * @param key Group property name. + * @param value Group property value. + * @return This builder. + */ public fun groupProperty( type: String, key: String, @@ -57,30 +113,58 @@ public class PostHogEvaluateFlagsOptions private constructor( return this } + /** + * Appends multiple group properties for flag evaluation. + * + * @param groupProperties Group properties to merge, keyed by group type. + * @return This builder. + */ public fun groupProperties(groupProperties: Map>): Builder { this.groupProperties = (this.groupProperties ?: mutableMapOf()).apply { putAll(groupProperties) } return this } /** - * Restrict the underlying `/flags` request to the given keys. This scopes what the server - * computes; the snapshot's `only(...)` helper, by contrast, filters in memory. + * Restricts the underlying `/flags` request to the given keys. + * + * This scopes what the server computes; the snapshot's `only(...)` helper, by contrast, + * filters in memory. + * + * @param flagKeys Feature flag keys to request. + * @return This builder. */ public fun flagKeys(flagKeys: List): Builder { this.flagKeys = (this.flagKeys ?: mutableListOf()).apply { addAll(flagKeys) } return this } + /** + * Sets whether the SDK should skip the remote fallback when local evaluation is inconclusive. + * + * @param onlyEvaluateLocally true to evaluate only locally; false to allow remote fallback. + * @return This builder. + */ public fun onlyEvaluateLocally(onlyEvaluateLocally: Boolean): Builder { this.onlyEvaluateLocally = onlyEvaluateLocally return this } + /** + * Sets whether the remote evaluation request should disable GeoIP property lookup. + * + * @param disableGeoip true to send `geoip_disable=true`. + * @return This builder. + */ public fun disableGeoip(disableGeoip: Boolean): Builder { this.disableGeoip = disableGeoip return this } + /** + * Builds an immutable [PostHogEvaluateFlagsOptions] instance. + * + * @return Evaluate-flags options containing the accumulated values. + */ public fun build(): PostHogEvaluateFlagsOptions = PostHogEvaluateFlagsOptions( groups, @@ -93,6 +177,11 @@ public class PostHogEvaluateFlagsOptions private constructor( } public companion object { + /** + * Creates a new Java-friendly evaluate-flags options builder. + * + * @return A new [Builder]. + */ @JvmStatic public fun builder(): Builder = Builder() } diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagEvaluations.kt b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagEvaluations.kt index 0e402bbe2..fa6149ce3 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagEvaluations.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagEvaluations.kt @@ -21,6 +21,11 @@ import java.util.Collections * * Filtered clones from [onlyAccessed] / [only] are independent of the parent — accessing flags on * the clone does not back-propagate into the parent's "accessed" set. + * + * @property distinctId The distinct ID the snapshot was evaluated for, or null for an empty snapshot. + * @property requestId Request ID returned by the `/flags` API, when available. + * @property evaluatedAt Server evaluation timestamp, when available. + * @property definitionsLoadedAt Local evaluation definitions timestamp, when available. */ public class PostHogFeatureFlagEvaluations internal constructor( public val distinctId: String?, @@ -41,7 +46,11 @@ public class PostHogFeatureFlagEvaluations internal constructor( private val accessLock = Any() private val accessed: MutableSet = HashSet(initialAccessed) - /** Returns the snapshotted flag keys in iteration order of the underlying map. */ + /** + * Returns the snapshotted flag keys in iteration order of the underlying map. + * + * @return Feature flag keys included in this snapshot. + */ public val keys: List get() = flagMap.keys.toList() @@ -58,6 +67,9 @@ public class PostHogFeatureFlagEvaluations internal constructor( * Returns whether the flag is enabled. Unknown flags return false. Records access; fires a * deduped `$feature_flag_called` event (with `$feature_flag_error: flag_missing` for unknown * keys), except when this snapshot has no resolvable distinctId. + * + * @param key Feature flag key. + * @return true when the flag is enabled or has a non-empty variant; false otherwise. */ public fun isEnabled(key: String): Boolean { val flag = flagMap[key] @@ -71,6 +83,9 @@ public class PostHogFeatureFlagEvaluations internal constructor( * is unknown. Records access; fires a deduped `$feature_flag_called` event (with * `$feature_flag_error: flag_missing` for unknown keys), except when this snapshot has no * resolvable distinctId. + * + * @param key Feature flag key. + * @return The variant string, boolean enabled value, or null when unknown. */ public fun getFlag(key: String): Any? { val flag = flagMap[key] @@ -83,6 +98,9 @@ public class PostHogFeatureFlagEvaluations internal constructor( * Returns the raw payload string for the flag, or null when the flag is unknown or has no * payload. The server returns payloads as JSON-encoded strings; use [getFlagPayloadAs] when * you want the deserialized value. Does not fire any event and does not record the access. + * + * @param key Feature flag key. + * @return The raw JSON payload string, or null when absent. */ public fun getFlagPayload(key: String): String? { return flagMap[key]?.metadata?.payload @@ -91,6 +109,9 @@ public class PostHogFeatureFlagEvaluations internal constructor( /** * Returns the flag payload deserialized from JSON to type [T], or null when the flag is * unknown, has no payload, or deserialization fails. + * + * @param key Feature flag key. + * @return The deserialized payload, or null when absent or invalid. */ public inline fun getFlagPayloadAs(key: String): T? = getFlagPayloadAs(key, T::class.java) @@ -98,6 +119,10 @@ public class PostHogFeatureFlagEvaluations internal constructor( * Returns the flag payload deserialized from JSON to [clazz], or null when the flag is * unknown, has no payload, or deserialization fails. The server returns payloads as * JSON-encoded strings, so this parses the raw string with Gson. + * + * @param key Feature flag key. + * @param clazz Class to deserialize the payload into. + * @return The deserialized payload, or null when absent or invalid. */ public fun getFlagPayloadAs( key: String, @@ -116,6 +141,8 @@ public class PostHogFeatureFlagEvaluations internal constructor( /** * Returns a filtered snapshot containing only the flags accessed on this instance via * [isEnabled] or [getFlag]. Returns an empty snapshot when no flag has been accessed yet. + * + * @return A new snapshot containing only accessed flags. */ public fun onlyAccessed(): PostHogFeatureFlagEvaluations { val accessedKeys = @@ -126,6 +153,9 @@ public class PostHogFeatureFlagEvaluations internal constructor( /** * Returns a filtered snapshot containing only the named flags. Unknown keys are dropped and * each one logs a warning so callers notice typos. + * + * @param keys Feature flag keys to keep. + * @return A new snapshot containing only the requested known flags. */ public fun only(keys: Collection): PostHogFeatureFlagEvaluations { val resolved = LinkedHashSet() @@ -142,7 +172,12 @@ public class PostHogFeatureFlagEvaluations internal constructor( return cloneWith(resolved) } - /** Java-friendly varargs alias of [only]. */ + /** + * Java-friendly varargs alias of [only]. + * + * @param keys Feature flag keys to keep. + * @return A new snapshot containing only the requested known flags. + */ public fun only(vararg keys: String): PostHogFeatureFlagEvaluations = only(keys.toList()) private fun cloneWith(keep: Collection): PostHogFeatureFlagEvaluations { diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagOptions.kt b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagOptions.kt index d8a798d24..72dc70701 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagOptions.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagOptions.kt @@ -1,8 +1,15 @@ package com.posthog.server /** - * Provides an ergonomic interface when providing options for capturing events - * This is mainly meant to be used from Java, as Kotlin can use named parameters. + * Java-friendly options for deprecated one-off feature flag lookup methods. + * + * Prefer [PostHogInterface.evaluateFlags] for new code so multiple flag reads can share one + * evaluation snapshot. + * + * @property defaultValue Value returned when the flag is missing or unavailable. + * @property groups Groups for group-based flags, keyed by group type. + * @property personProperties Person properties to use for flag evaluation. + * @property groupProperties Group properties to use for flag evaluation, keyed by group type. */ public class PostHogFeatureFlagOptions private constructor( public val defaultValue: Any?, @@ -10,14 +17,27 @@ public class PostHogFeatureFlagOptions private constructor( public val personProperties: Map?, public val groupProperties: Map>?, ) { + /** + * Mutable builder for [PostHogFeatureFlagOptions]. + */ public class Builder { + /** Value returned when the flag is missing or unavailable. */ public var defaultValue: Any? = null + + /** Groups for group-based flags, keyed by group type. */ public var groups: MutableMap? = null + + /** Person properties used for flag evaluation. */ public var personProperties: MutableMap? = null + + /** Group properties used for flag evaluation, keyed by group type. */ public var groupProperties: MutableMap>? = null /** - * Sets the default value to return if the feature flag is not found or not enabled + * Sets the default value to return if the feature flag is not found or unavailable. + * + * @param defaultValue Default value for the lookup. + * @return This builder. */ public fun defaultValue(defaultValue: Any?): Builder { this.defaultValue = defaultValue @@ -25,7 +45,11 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Add a single custom property to the capture options + * Adds a single group for group-based flag evaluation. + * + * @param key Group type, for example `company`. + * @param propValue Group key or identifier. + * @return This builder. */ public fun group( key: String, @@ -39,7 +63,10 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Appends multiple groups to the feature flag options + * Appends multiple groups for group-based flag evaluation. + * + * @param groups Groups to merge, keyed by group type. + * @return This builder. */ public fun groups(groups: Map): Builder { this.groups = @@ -50,7 +77,11 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Adds a single user property to the capture options + * Adds a single person property for flag evaluation. + * + * @param key Person property name. + * @param propValue Person property value. + * @return This builder. * @see Documentation: User Properties */ public fun personProperty( @@ -65,7 +96,10 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Appends multiple user properties to the capture options. + * Appends multiple person properties for flag evaluation. + * + * @param userProperties Person properties to merge. + * @return This builder. * @see Documentation: User Properties */ public fun personProperties(userProperties: Map): Builder { @@ -77,8 +111,12 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Adds a single user property (set once) to the capture options. - * @see Documentation: User Properties + * Adds a single group property for flag evaluation. + * + * @param group Group type, for example `company`. + * @param key Group property name. + * @param propValue Group property value. + * @return This builder. */ public fun groupProperty( group: String, @@ -93,8 +131,10 @@ public class PostHogFeatureFlagOptions private constructor( } /** - * Appends multiple user properties (set once) to the capture options. - * @see Documentation: User Properties + * Appends multiple group properties for flag evaluation. + * + * @param groupProperties Group properties to merge, keyed by group type. + * @return This builder. */ public fun groupProperties(groupProperties: Map>): Builder { this.groupProperties = @@ -106,6 +146,11 @@ public class PostHogFeatureFlagOptions private constructor( return this } + /** + * Builds an immutable [PostHogFeatureFlagOptions] instance. + * + * @return Feature-flag lookup options containing the accumulated values. + */ public fun build(): PostHogFeatureFlagOptions = PostHogFeatureFlagOptions( defaultValue = defaultValue, @@ -116,6 +161,11 @@ public class PostHogFeatureFlagOptions private constructor( } public companion object { + /** + * Creates a new Java-friendly feature flag options builder. + * + * @return A new [Builder]. + */ @JvmStatic public fun builder(): Builder = Builder() } diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagResultOptions.kt b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagResultOptions.kt index 72fbdb70a..dcc7068aa 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagResultOptions.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogFeatureFlagResultOptions.kt @@ -1,8 +1,15 @@ package com.posthog.server /** - * Provides an ergonomic interface when providing options for getFeatureFlagResult. - * This is mainly meant to be used from Java, as Kotlin can use named parameters. + * Java-friendly options for deprecated one-off feature flag result lookups. + * + * Prefer [PostHogInterface.evaluateFlags] for new code so flag values and payloads can be read + * from one evaluation snapshot. + * + * @property groups Groups for group-based flags, keyed by group type. + * @property personProperties Person properties to use for flag evaluation. + * @property groupProperties Group properties to use for flag evaluation, keyed by group type. + * @property sendFeatureFlagEvent Whether to send `$feature_flag_called`, or null to use the SDK config default. */ public class PostHogFeatureFlagResultOptions private constructor( public val groups: Map?, @@ -10,15 +17,29 @@ public class PostHogFeatureFlagResultOptions private constructor( public val groupProperties: Map>?, public val sendFeatureFlagEvent: Boolean?, ) { + /** + * Mutable builder for [PostHogFeatureFlagResultOptions]. + */ public class Builder { + /** Groups for group-based flags, keyed by group type. */ public var groups: MutableMap? = null + + /** Person properties used for flag evaluation. */ public var personProperties: MutableMap? = null + + /** Group properties used for flag evaluation, keyed by group type. */ public var groupProperties: MutableMap>? = null + + /** Whether to send `$feature_flag_called`, or null to use the SDK config default. */ public var sendFeatureFlagEvent: Boolean? = null /** - * Sets whether to send the $feature_flag_called event when the flag is evaluated. - * When null, uses the default behavior from PostHogConfig.sendFeatureFlagEvent. + * Sets whether to send the `$feature_flag_called` event when the flag is evaluated. + * + * When null, uses the default behavior from [PostHogConfig.sendFeatureFlagEvent]. + * + * @param sendFeatureFlagEvent true to send, false to suppress, or null to use the config default. + * @return This builder. */ public fun sendFeatureFlagEvent(sendFeatureFlagEvent: Boolean?): Builder { this.sendFeatureFlagEvent = sendFeatureFlagEvent @@ -26,7 +47,11 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Add a single custom property to the capture options + * Adds a single group for group-based flag evaluation. + * + * @param key Group type, for example `company`. + * @param propValue Group key or identifier. + * @return This builder. */ public fun group( key: String, @@ -40,7 +65,10 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Appends multiple groups to the feature flag options + * Appends multiple groups for group-based flag evaluation. + * + * @param groups Groups to merge, keyed by group type. + * @return This builder. */ public fun groups(groups: Map): Builder { this.groups = @@ -51,7 +79,11 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Adds a single user property to the capture options + * Adds a single person property for flag evaluation. + * + * @param key Person property name. + * @param propValue Person property value. + * @return This builder. * @see Documentation: User Properties */ public fun personProperty( @@ -66,7 +98,10 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Appends multiple user properties to the capture options. + * Appends multiple person properties for flag evaluation. + * + * @param userProperties Person properties to merge. + * @return This builder. * @see Documentation: User Properties */ public fun personProperties(userProperties: Map): Builder { @@ -78,8 +113,12 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Adds a single user property (set once) to the capture options. - * @see Documentation: User Properties + * Adds a single group property for flag evaluation. + * + * @param group Group type, for example `company`. + * @param key Group property name. + * @param propValue Group property value. + * @return This builder. */ public fun groupProperty( group: String, @@ -94,8 +133,10 @@ public class PostHogFeatureFlagResultOptions private constructor( } /** - * Appends multiple user properties (set once) to the capture options. - * @see Documentation: User Properties + * Appends multiple group properties for flag evaluation. + * + * @param groupProperties Group properties to merge, keyed by group type. + * @return This builder. */ public fun groupProperties(groupProperties: Map>): Builder { this.groupProperties = @@ -107,6 +148,11 @@ public class PostHogFeatureFlagResultOptions private constructor( return this } + /** + * Builds an immutable [PostHogFeatureFlagResultOptions] instance. + * + * @return Feature-flag result lookup options containing the accumulated values. + */ public fun build(): PostHogFeatureFlagResultOptions = PostHogFeatureFlagResultOptions( groups = groups, @@ -117,6 +163,11 @@ public class PostHogFeatureFlagResultOptions private constructor( } public companion object { + /** + * Creates a new Java-friendly feature flag result options builder. + * + * @return A new [Builder]. + */ @JvmStatic public fun builder(): Builder = Builder() } diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogInterface.kt b/posthog-server/src/main/java/com/posthog/server/PostHogInterface.kt index 1fee60719..67aa1fea6 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogInterface.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogInterface.kt @@ -3,6 +3,9 @@ package com.posthog.server import com.posthog.FeatureFlagResult import java.util.Date +/** + * Public server-side SDK client API. + */ public sealed interface PostHogInterface { /** * Setup the SDK @@ -65,6 +68,7 @@ public sealed interface PostHogInterface { /** * Enables or disables the debug mode + * @param enable true to enable SDK debug logging, false to disable it. */ public fun debug(enable: Boolean) @@ -99,6 +103,15 @@ public sealed interface PostHogInterface { /** * Captures an event using the current [PostHogRequestContext] distinct ID, or as a personless * event when no request context identity is active. + * + * @param event the event name + * @param properties the custom properties + * @param userProperties the user properties, set as a "$set" property + * @param userPropertiesSetOnce the user properties to set only once, set as a "$set_once" property + * @param groups the groups, set as a "$groups" property + * @param timestamp the timestamp for the event + * @param appendFeatureFlags when true, enriches the event with feature flag properties + * @param flags optional pre-resolved snapshot from [evaluateFlags] */ @JvmSynthetic public fun capture( @@ -129,7 +142,8 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId. When null or blank, the current [PostHogRequestContext] * distinct ID is used; if none exists, a personless UUID is generated. * @param event the event name - * @param options the capture options containing properties, userProperties, userPropertiesSetOnce, groups, and appendFeatureFlags + * @param options capture options containing properties, user properties, groups, timestamp, + * and feature flag snapshot settings */ public fun capture( distinctId: String?, @@ -152,6 +166,9 @@ public sealed interface PostHogInterface { /** * Captures an event using the current [PostHogRequestContext] distinct ID, or as a personless * event when no request context identity is active. + * + * @param event the event name + * @param options capture options containing properties, groups, timestamp, and feature flag snapshot settings */ public fun capture( event: String, @@ -190,6 +207,8 @@ public sealed interface PostHogInterface { /** * Captures an event using the current [PostHogRequestContext] distinct ID, or as a personless * event when no request context identity is active. + * + * @param event the event name */ public fun capture(event: String) { capture( @@ -204,6 +223,10 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found, false if not given + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return Whether the feature flag is enabled. */ @Deprecated( message = @@ -224,6 +247,7 @@ public sealed interface PostHogInterface { * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param distinctId the distinctId * @param key the Key + * @return Whether the feature flag is enabled. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).isEnabled(key). Will be removed in the next major.", @@ -249,6 +273,7 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @return Whether the feature flag is enabled. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).isEnabled(key). Will be removed in the next major.", @@ -275,6 +300,7 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param options the feature flag options containing defaultValue, groups, personProperties, and groupProperties + * @return Whether the feature flag is enabled. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).isEnabled(key). Will be removed in the next major.", @@ -301,6 +327,10 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return The feature flag value, or [defaultValue] if not found. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).getFlag(key). Will be removed in the next major.", @@ -345,6 +375,7 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param options the feature flag options containing defaultValue, groups, personProperties, and groupProperties + * @return The feature flag value, or the options default value if not found. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).getFlag(key). Will be removed in the next major.", @@ -366,11 +397,12 @@ public sealed interface PostHogInterface { } /** - * Returns if a feature flag is enabled, the feature flag must be a Boolean + * Returns the feature flags variant if multi-variant, otherwise whether it is enabled or not * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @return The feature flag value, or [defaultValue] if not found. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).getFlag(key). Will be removed in the next major.", @@ -397,6 +429,10 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return The feature flag payload, or [defaultValue] if not found. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).getFlagPayload(key). Will be removed in the next major.", @@ -441,6 +477,7 @@ public sealed interface PostHogInterface { * @param distinctId the distinctId * @param key the Key * @param options the feature flag options containing defaultValue, groups, personProperties, and groupProperties + * @return The feature flag payload, or the options default value if not found. */ @Deprecated( message = "Prefer evaluateFlags(distinctId).getFlagPayload(key). Will be removed in the next major.", @@ -624,6 +661,7 @@ public sealed interface PostHogInterface { * @param onlyEvaluateLocally when true, do not fall back to a `/flags` request if local * evaluation cannot resolve every flag * @param disableGeoip when true, send `geoip_disable=true` to the server + * @return A feature flag evaluation snapshot for the resolved distinct ID. */ @JvmSynthetic public fun evaluateFlags( @@ -639,6 +677,11 @@ public sealed interface PostHogInterface { /** * Evaluate every feature flag for [distinctId] using the supplied options object. * Java-friendly overload that mirrors the canonical [evaluateFlags] entry point. + * + * @param distinctId the distinctId. When null or blank, the current [PostHogRequestContext] + * distinct ID is used; if none exists, an empty snapshot is returned. + * @param options Evaluation options. + * @return A feature flag evaluation snapshot for the resolved distinct ID. */ public fun evaluateFlags( distinctId: String?, @@ -658,6 +701,9 @@ public sealed interface PostHogInterface { /** * Evaluate every feature flag using the current [PostHogRequestContext] distinct ID and the * supplied options object. Returns an empty snapshot when no request context identity is active. + * + * @param options Evaluation options. + * @return A feature flag evaluation snapshot, or an empty snapshot when no identity is active. */ public fun evaluateFlags(options: PostHogEvaluateFlagsOptions): PostHogFeatureFlagEvaluations { return evaluateFlags( @@ -668,6 +714,10 @@ public sealed interface PostHogInterface { /** * Evaluate every feature flag for [distinctId] using default options. + * + * @param distinctId the distinctId. When null or blank, the current [PostHogRequestContext] + * distinct ID is used; if none exists, an empty snapshot is returned. + * @return A feature flag evaluation snapshot for the resolved distinct ID. */ public fun evaluateFlags(distinctId: String?): PostHogFeatureFlagEvaluations { return evaluateFlags( @@ -684,6 +734,8 @@ public sealed interface PostHogInterface { /** * Evaluate every feature flag using the current [PostHogRequestContext] distinct ID. Returns an * empty snapshot when no request context identity is active. + * + * @return A feature flag evaluation snapshot, or an empty snapshot when no identity is active. */ public fun evaluateFlags(): PostHogFeatureFlagEvaluations { return evaluateFlags(distinctId = null) @@ -715,7 +767,6 @@ public sealed interface PostHogInterface { * Captures an exception * Docs https://posthog.com/docs/error-tracking * @param exception the exception to capture - * @param properties the exception properties to add to the event * @param distinctId the distinctId */ public fun captureException( @@ -733,7 +784,6 @@ public sealed interface PostHogInterface { * Captures an exception * Docs https://posthog.com/docs/error-tracking * @param exception the exception to capture - * @param distinctId the distinctId * @param properties the exception properties to add to the event */ public fun captureException( @@ -751,8 +801,6 @@ public sealed interface PostHogInterface { * Captures an exception * Docs https://posthog.com/docs/error-tracking * @param exception the exception to capture - * @param properties the exception properties to add to the event - * @param distinctId the distinctId */ public fun captureException(exception: Throwable) { captureException( diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogRequestContext.kt b/posthog-server/src/main/java/com/posthog/server/PostHogRequestContext.kt index 0b972d295..edcc5fd01 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogRequestContext.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogRequestContext.kt @@ -26,6 +26,8 @@ public class PostHogRequestContext private constructor() { /** * Returns the context active on the current thread, or null when no scope is active. + * + * @return The current request context, or null. */ @JvmStatic public fun current(): PostHogRequestContextData? = currentContext.get() @@ -34,12 +36,19 @@ public class PostHogRequestContext private constructor() { * Starts a request context scope and returns an [AutoCloseable] that restores the previous context. * * Nested scopes inherit the current context by default. Pass [fresh] to start from an empty context. + * + * @param data Context data to apply within the scope. + * @return A scope that restores the previous context when closed. */ @JvmStatic public fun beginScope(data: PostHogRequestContextData): Scope = beginScope(data, fresh = false) /** * Starts a request context scope and returns an [AutoCloseable] that restores the previous context. + * + * @param data Context data to apply within the scope. + * @param fresh Whether to ignore any existing context instead of inheriting it. + * @return A scope that restores the previous context when closed. */ @JvmStatic public fun beginScope( @@ -54,6 +63,10 @@ public class PostHogRequestContext private constructor() { /** * Runs [block] inside a request context scope and restores the previous context afterwards. + * + * @param data Context data to apply while running [block]. + * @param block Work to run inside the scope. + * @return The value returned by [block]. */ public fun withContext( data: PostHogRequestContextData, @@ -62,6 +75,11 @@ public class PostHogRequestContext private constructor() { /** * Runs [block] inside a request context scope and restores the previous context afterwards. + * + * @param data Context data to apply while running [block]. + * @param fresh Whether to ignore any existing context instead of inheriting it. + * @param block Work to run inside the scope. + * @return The value returned by [block]. */ public fun withContext( data: PostHogRequestContextData, @@ -79,6 +97,11 @@ public class PostHogRequestContext private constructor() { * Header names are matched case-insensitively. Values are trimmed, control characters are * removed, empty values are ignored, and long values are capped. When [captureTracingHeaders] * is false, tracing headers are ignored but [properties] are still preserved. + * + * @param headers Headers to inspect. Values may be strings, arrays, or iterables. + * @param captureTracingHeaders Whether to read PostHog tracing headers from [headers]. + * @param properties Request properties to attach to captures inside the scope. + * @return Context data resolved from the supplied headers and properties. */ @JvmStatic @JvmOverloads @@ -241,6 +264,10 @@ public class PostHogRequestContext private constructor() { /** * Values applied to captures made inside a [PostHogRequestContext] scope. + * + * @property distinctId Distinct ID to use for captures and feature flag evaluation. + * @property sessionId Session ID to attach as `$session_id` when available. + * @property properties Common properties to merge into captures inside the scope. */ public class PostHogRequestContextData public constructor( public val distinctId: String? = null, diff --git a/posthog/src/main/java/com/posthog/PersonProfiles.kt b/posthog/src/main/java/com/posthog/PersonProfiles.kt index bb31fcbb8..be762f960 100644 --- a/posthog/src/main/java/com/posthog/PersonProfiles.kt +++ b/posthog/src/main/java/com/posthog/PersonProfiles.kt @@ -1,7 +1,15 @@ package com.posthog +/** + * Controls when captured events should create or update PostHog person profiles. + */ public enum class PersonProfiles { + /** Never process person profile data. Anonymous users are not merged when they identify. */ NEVER, + + /** Process person profile data for all captured events. */ ALWAYS, + + /** Process person profile data only after `identify`, `alias`, or `group` calls. */ IDENTIFIED_ONLY, } diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 2980c3217..a5560c958 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -1718,9 +1718,10 @@ public class PostHog private constructor( } /** - * Set up the SDK and returns an instance that you can hold and pass it around - * @param T the type of the Config - * @property config the Config + * Sets up the SDK and returns an instance that you can hold and pass around. + * + * @param config SDK configuration. + * @return The configured PostHog client instance. */ public fun with(config: T): PostHogInterface { val instance = PostHog() diff --git a/posthog/src/main/java/com/posthog/PostHogBeforeSend.kt b/posthog/src/main/java/com/posthog/PostHogBeforeSend.kt index fcf282972..1788e1e8e 100644 --- a/posthog/src/main/java/com/posthog/PostHogBeforeSend.kt +++ b/posthog/src/main/java/com/posthog/PostHogBeforeSend.kt @@ -1,5 +1,16 @@ package com.posthog +/** + * Hook invoked before an analytics event is queued. + * + * Return the same or a modified [PostHogEvent] to continue, or `null` to drop the event. + */ public fun interface PostHogBeforeSend { + /** + * Runs the hook for [event]. + * + * @param event Event about to be queued. + * @return The event to queue, or `null` to drop it. + */ public fun run(event: PostHogEvent): PostHogEvent? } diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index abcf957ff..9ca772fd4 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -31,7 +31,7 @@ import java.util.concurrent.ExecutorService */ public open class PostHogConfig( /** - * The PostHog API Key + * The PostHog project API key. */ apiKey: String, /** @@ -48,7 +48,7 @@ public open class PostHogConfig( public var debug: Boolean = false, /** * This flag prevents capturing any data if enabled - * You can overwrite this value at runtime by calling [PostHog.optIn()]] or PostHog.optOut() + * You can overwrite this value at runtime by calling [PostHog.optIn] or [PostHog.optOut] * Defaults to false */ @Volatile @@ -350,7 +350,7 @@ public open class PostHogConfig( public var httpClient: OkHttpClient? = null /** - * The PostHog API Key + * The PostHog project API key, trimmed of leading and trailing whitespace. */ public val apiKey: String = apiKey.trim() diff --git a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt index 0e199fc73..dc77ef3a3 100644 --- a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt @@ -47,6 +47,7 @@ public interface PostHogCoreInterface { /** * Enables or disables the debug mode + * @param enable true to enable SDK debug logging, false to disable it. */ public fun debug(enable: Boolean = true) } diff --git a/posthog/src/main/java/com/posthog/PostHogEncryption.kt b/posthog/src/main/java/com/posthog/PostHogEncryption.kt index bf1ce417e..e4087245f 100644 --- a/posthog/src/main/java/com/posthog/PostHogEncryption.kt +++ b/posthog/src/main/java/com/posthog/PostHogEncryption.kt @@ -9,14 +9,16 @@ import java.io.OutputStream */ public interface PostHogEncryption { /** - * The decrypt method + * Decrypts data read from [inputStream]. * @param inputStream the InputStream that has to be decrypted + * @return an InputStream that yields decrypted event data */ public fun decrypt(inputStream: InputStream): InputStream /** - * The decrypt method + * Encrypts data written to [outputStream]. * @param outputStream the OutputStream that has to be encrypted + * @return an OutputStream that writes encrypted event data */ public fun encrypt(outputStream: OutputStream): OutputStream } diff --git a/posthog/src/main/java/com/posthog/PostHogIntegration.kt b/posthog/src/main/java/com/posthog/PostHogIntegration.kt index e4cfba998..85aea768b 100644 --- a/posthog/src/main/java/com/posthog/PostHogIntegration.kt +++ b/posthog/src/main/java/com/posthog/PostHogIntegration.kt @@ -7,6 +7,7 @@ public interface PostHogIntegration { /** * Install the Integration after the SDK is setup * that requires a posthog instance to capture events + * @param postHog the configured SDK instance. */ public fun install(postHog: PostHogInterface) { } diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index e7daba84e..49dcd1d49 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -27,6 +27,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Captures events + * @param event the event name * @param distinctId the distinctId, the generated [distinctId] is used if not given * @param properties the custom properties * @param userProperties the user properties, set as a "$set" property, Docs https://posthog.com/docs/product-analytics/user-properties @@ -65,7 +66,8 @@ public interface PostHogInterface : PostHogCoreInterface { * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param key the Key * @param defaultValue the default value if not found, false if not given - * @param sendFeatureFlagEvent (optional) If false, we won't send an $feature_flag_call event to PostHog. + * @param sendFeatureFlagEvent (optional) If false, we won't send an $feature_flag_called event to PostHog. + * @return Whether the feature flag is enabled. */ public fun isFeatureEnabled( key: String, @@ -78,7 +80,8 @@ public interface PostHogInterface : PostHogCoreInterface { * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param key the Key * @param defaultValue the default value if not found - * @param sendFeatureFlagEvent (optional) If false, we won't send an $feature_flag_call event to PostHog. + * @param sendFeatureFlagEvent (optional) If false, we won't send an $feature_flag_called event to PostHog. + * @return The feature flag value, or [defaultValue] if not found. */ public fun getFeatureFlag( key: String, @@ -89,6 +92,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * 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. */ public fun getAllFeatureFlags(): List? @@ -97,6 +101,7 @@ public interface PostHogInterface : PostHogCoreInterface { * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param key the Key * @param defaultValue the default value if not found + * @return The feature flag payload, or [defaultValue] if not found. */ public fun getFeatureFlagPayload( key: String, @@ -175,6 +180,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Returns the registered [distinctId] property + * @return The current distinct ID. */ public fun distinctId(): String @@ -204,12 +210,14 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Returns if a session is active + * @return Whether a session is currently active. */ public fun isSessionActive(): Boolean /** * Returns if Session Replay is Active * Android only. + * @return Whether session replay is currently active. */ public fun isSessionReplayActive(): Boolean @@ -236,6 +244,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Returns the session Id if a session is active + * @return The current session ID, or null if no session is active. */ public fun getSessionId(): UUID? @@ -261,7 +270,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Sets person properties that will be included in feature flag evaluation requests. * - * @param properties Dictionary of person properties to include in flag evaluation + * @param userProperties Dictionary of person properties to include in flag evaluation * @param reloadFeatureFlags Whether to automatically reload feature flags after setting properties */ public fun setPersonPropertiesForFlags( @@ -279,7 +288,7 @@ public interface PostHogInterface : PostHogCoreInterface { * Sets properties for a specific group type to include when evaluating feature flags. * * @param type The group type identifier (e.g., "organization", "team") - * @param properties Dictionary of properties to set for this group type + * @param groupProperties Dictionary of properties to set for this group type * @param reloadFeatureFlags Whether to automatically reload feature flags after setting properties */ public fun setGroupPropertiesForFlags( diff --git a/posthog/src/main/java/com/posthog/PostHogOkHttpInterceptor.kt b/posthog/src/main/java/com/posthog/PostHogOkHttpInterceptor.kt index e8addb109..cc18f81e2 100644 --- a/posthog/src/main/java/com/posthog/PostHogOkHttpInterceptor.kt +++ b/posthog/src/main/java/com/posthog/PostHogOkHttpInterceptor.kt @@ -13,6 +13,9 @@ import okhttp3.Response * * Install this interceptor on each [okhttp3.OkHttpClient] whose requests should be captured or * annotated with tracing headers. + * + * @param captureNetworkTelemetry Whether to capture network timing telemetry for session replay. + * @param postHog Optional SDK instance to use; when omitted, the global [PostHog] singleton is used. */ public class PostHogOkHttpInterceptor( private var captureNetworkTelemetry: Boolean = true, diff --git a/posthog/src/main/java/com/posthog/PostHogStateless.kt b/posthog/src/main/java/com/posthog/PostHogStateless.kt index 91ea7e509..7b487580b 100644 --- a/posthog/src/main/java/com/posthog/PostHogStateless.kt +++ b/posthog/src/main/java/com/posthog/PostHogStateless.kt @@ -629,9 +629,10 @@ public open class PostHogStateless protected constructor( } /** - * Set up the SDK and returns an instance that you can hold and pass it around - * @param T the type of the Config - * @property config the Config + * Sets up the stateless SDK and returns an instance that you can hold and pass around. + * + * @param config SDK configuration. + * @return The configured stateless PostHog client instance. */ public fun with(config: T): PostHogStatelessInterface { val instance = PostHogStateless() diff --git a/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt b/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt index 7493bd778..c37feb816 100644 --- a/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt @@ -8,6 +8,7 @@ import java.util.Date public interface PostHogStatelessInterface : PostHogCoreInterface { /** * Captures events + * @param event the event name * @param distinctId the distinctId of the user performing the event * @param properties the custom properties * @param userProperties the user properties, set as a "$set" property, Docs https://posthog.com/docs/product-analytics/user-properties @@ -31,6 +32,10 @@ public interface PostHogStatelessInterface : PostHogCoreInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found, false if not given + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return Whether the feature flag is enabled. */ public fun isFeatureEnabledStateless( distinctId: String, @@ -47,6 +52,10 @@ public interface PostHogStatelessInterface : PostHogCoreInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return The feature flag value, or [defaultValue] if not found. */ public fun getFeatureFlagStateless( distinctId: String, @@ -63,6 +72,10 @@ public interface PostHogStatelessInterface : PostHogCoreInterface { * @param distinctId the distinctId * @param key the Key * @param defaultValue the default value if not found + * @param groups groups for group-based flags + * @param personProperties person properties for flag evaluation + * @param groupProperties group properties for flag evaluation + * @return The feature flag payload, or [defaultValue] if not found. */ public fun getFeatureFlagPayloadStateless( distinctId: String, @@ -81,6 +94,7 @@ public interface PostHogStatelessInterface : PostHogCoreInterface { * @param groups the groups for group-based flags * @param personProperties person properties for flag evaluation * @param groupProperties group properties for flag evaluation + * @param sendFeatureFlagEvent whether to send the $feature_flag_called event, or null to use config default * @return FeatureFlagResult if the flag exists, null otherwise */ public fun getFeatureFlagResultStateless( diff --git a/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingConfig.kt b/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingConfig.kt index 49f441cff..cba4bd72f 100644 --- a/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingConfig.kt +++ b/posthog/src/main/java/com/posthog/errortracking/PostHogErrorTrackingConfig.kt @@ -2,6 +2,9 @@ package com.posthog.errortracking import com.posthog.PostHog +/** + * Configuration for PostHog error tracking. + */ public class PostHogErrorTrackingConfig @JvmOverloads public constructor(