Package net.hollowcube.posthog

Interface PostHogClient

All Known Implementing Classes:
PostHogClientImpl
public sealed interface PostHogClient permits PostHogClientImpl (not exhaustive)
Represents the available API surface for PostHog. Used internally by the global PostHog.

Multiple clients may be created and managed independently.

Methods are non-blocking unless otherwise specified.

  • Method Details

    • noopPostHogClient

      @NotNull static @NotNull PostHogClient noopPostHogClient()

    • newPostHogClient

      @NotNull static @NotNull PostHogClient newPostHogClient(@NotNull @NotNull String projectApiKey)

    • newBuilder

      @NotNull static @NotNull PostHogClient.Builder newBuilder(@NotNull @NotNull String projectApiKey)

    • shutdown

      @Blocking void shutdown(@NotNull @NotNull Duration timeout)

    • capture

      default void capture(@NotNull @NotNull String distinctId, @NotNull @NotNull String event)
      Capture an event with the given name for the given distinct ID with no properties.
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      event - Name of the event. May not be empty.

    • capture

      default void capture(@NotNull @NotNull String distinctId, @NotNull @NotNull String event, @NotNull @NotNull Map<String,Object> properties)
      Capture an event with the given name for the given distinct ID with the provided properties.
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      event - Name of the event. May not be empty.
      properties - Event properties

    • capture

      void capture(@NotNull @NotNull String distinctId, @NotNull @NotNull String event, @NotNull @NotNull Object properties)
      Capture an event with the given name for the given ID with properties from the given object.

      The object must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      event - Name of the event. May not be empty.
      properties - Event object data

    • identify

      default void identify(@NotNull @NotNull String distinctId, @Nullable @Nullable Map<String,Object> properties, @Nullable @Nullable Map<String,Object> propertiesSetOnce)
      Link the given properties with the person profile of the user (distinct id).
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile
      propertiesSetOnce - Properties to set only if missing on the person profile

    • identify

      default void identify(@NotNull @NotNull String distinctId, @Nullable @Nullable Object properties, @Nullable @Nullable Object propertiesSetOnce)
      Link the given properties with the person profile of the user (distinct id).

      The objects must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile
      propertiesSetOnce - Properties to set only if missing on the person profile

    • identify

      default void identify(@NotNull @NotNull String distinctId, @Nullable @Nullable Map<String,Object> properties)
      Link the given properties with the person profile of the user (distinct id).
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile

    • identify

      default void identify(@NotNull @NotNull String distinctId, @Nullable @Nullable Object properties)
      Link the given properties with the person profile of the user (distinct id).

      The object must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile

    • set

      default void set(@NotNull @NotNull String distinctId, @Nullable @Nullable Map<String,Object> properties, @Nullable @Nullable Map<String,Object> propertiesSetOnce)
      Set the given properties with the person profile of the user (distinct id).
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile
      propertiesSetOnce - Properties to set only if missing on the person profile

    • set

      default void set(@NotNull @NotNull String distinctId, @Nullable @Nullable Object properties, @Nullable @Nullable Object propertiesSetOnce)
      Set the given properties with the person profile of the user (distinct id).

      The objects must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile
      propertiesSetOnce - Properties to set only if missing on the person profile

    • set

      default void set(@NotNull @NotNull String distinctId, @Nullable @Nullable Map<String,Object> properties)
      Set the given properties with the person profile of the user (distinct id).
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile

    • set

      default void set(@NotNull @NotNull String distinctId, @Nullable @Nullable Object properties)
      Set the given properties with the person profile of the user (distinct id).

      The object must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      properties - Properties to set (including overwriting previous values) on the person profile

    • alias

      default void alias(@NotNull @NotNull String distinctId, @NotNull @NotNull String alias)
      Alias the given distinct ID to the given alias.
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty.
      alias - Alias to set for the distinct ID. May not be empty.

    • groupIdentify

      default void groupIdentify(@NotNull @NotNull String type, @NotNull @NotNull String key, @NotNull @NotNull Map<String,Object> properties)
      Assign the given properties to the given group (type & key).
      Parameters:
      type - Group type. Must not be empty
      key - Group key. Must not be empty
      properties - Properties to set (including overwriting previous values) on the group

    • groupIdentify

      default void groupIdentify(@NotNull @NotNull String type, @NotNull @NotNull String key, @NotNull @NotNull Object properties)
      Assign the given properties to the given group (type & key).

      The object must be serializable to a JSON object via Gson (not primitive or array)

      Parameters:
      type - Group type. Must not be empty
      key - Group key. Must not be empty
      properties - Properties to set (including overwriting previous values) on the group

    • flush

      void flush()
      Queue an immediate flush of the pending event queue. This call does not block on the flush to be completed.

    • isFeatureEnabled

      default boolean isFeatureEnabled(@NotNull @NotNull String key, @NotNull @NotNull String distinctId)
      Check if the given feature flag is enabled for the given distinct ID.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      Returns:
      True if the feature flag is enabled for the given distinct ID, false otherwise

    • isFeatureEnabled

      default boolean isFeatureEnabled(@NotNull @NotNull String key, @NotNull @NotNull String distinctId, @Nullable @Nullable FeatureFlagContext context)
      Check if the given feature flag is enabled for the given distinct ID with extra context.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      context - Extra context to pass to the feature flag evaluation
      Returns:
      True if the feature flag is enabled for the given distinct ID, false otherwise

    • getFeatureFlag

      @NotNull default @NotNull FeatureFlagState getFeatureFlag(@NotNull @NotNull String key, @NotNull @NotNull String distinctId)
      Get the feature flag state for the given distinct ID.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      Returns:
      Feature flag state

    • getFeatureFlag

      @NotNull @NotNull FeatureFlagState getFeatureFlag(@NotNull @NotNull String key, @NotNull @NotNull String distinctId, @Nullable @Nullable FeatureFlagContext context)
      Get the feature flag state for the given distinct ID with extra context.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      context - Extra context to pass to the feature flag evaluation
      Returns:
      Feature flag state

    • getFeatureFlagPayload

      @Nullable default @Nullable String getFeatureFlagPayload(@NotNull @NotNull String key, @NotNull @NotNull String distinctId)
      Get the feature flag payload for the given distinct ID.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      Returns:
      Feature flag payload, or null if the feature flag is disabled or has no payload configured.

    • getFeatureFlagPayload

      @Nullable default @Nullable String getFeatureFlagPayload(@NotNull @NotNull String key, @NotNull @NotNull String distinctId, @Nullable @Nullable FeatureFlagContext context)
      Get the feature flag payload for the given distinct ID.
      Parameters:
      key - Feature flag key
      distinctId - Unique ID of the target in your database. May not be empty
      context - Extra context to pass to the feature flag evaluation
      Returns:
      Feature flag payload, or null if the feature flag is disabled or has no payload configured.

    • getAllFeatureFlags

      @NotNull default @NotNull FeatureFlagStates getAllFeatureFlags(@NotNull @NotNull String distinctId)
      Get all feature flags for the given distinct ID.
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty
      Returns:
      Feature flag states

    • getAllFeatureFlags

      @NotNull @NotNull FeatureFlagStates getAllFeatureFlags(@NotNull @NotNull String distinctId, @Nullable @Nullable FeatureFlagContext context)
      Get all feature flags for the given distinct ID with extra context.
      Parameters:
      distinctId - Unique ID of the target in your database. May not be empty
      context - Extra context to pass to the feature flag evaluation
      Returns:
      Feature flag states

    • reloadFeatureFlags

      void reloadFeatureFlags()
      Triggers a full reload of all local feature flags from the remote server. Only valid when local evaluation is enabled. This call does not block on the flush to be completed.
      Throws:
      IllegalStateException - if local feature flag evaluation is not enabled.

    • captureException

      default void captureException(@NotNull @NotNull Throwable throwable)

    • captureException

      default void captureException(@NotNull @NotNull Throwable throwable, @NotNull @NotNull String distinctId)

    • captureException

      default void captureException(@NotNull @NotNull Throwable throwable, @NotNull @NotNull String distinctId, @NotNull @NotNull Map<String,Object> properties)

    • captureException

      void captureException(@NotNull @NotNull Throwable throwable, @Nullable @Nullable String distinctId, @Nullable @Nullable Object properties)