Posthog (posthog v0.4.2)

A comprehensive Elixir client for PostHog's analytics and feature flag APIs.

This module provides a high-level interface to PostHog's APIs, allowing you to:

Track user events and actions
Manage and evaluate feature flags
Handle multivariate testing
Process events in batch
Work with user, group, and person properties

Configuration

Add your PostHog configuration to your application config:

config :posthog,
  api_url: "https://app.posthog.com",  # Or your self-hosted instance
  api_key: "phc_your_project_api_key"

Optional configuration:

config :posthog,
  json_library: Jason,  # Default JSON parser (optional)
  version: 3           # API version (optional, defaults to 3)

Event Tracking

Events can be tracked with various levels of detail:

# Basic event
Posthog.capture("page_view", distinct_id: "user_123")

# Event with properties
Posthog.capture("purchase", [
  distinct_id: "user_123",
  properties: %{
    product_id: "prod_123",
    price: 99.99
  }
])

# Event with custom timestamp
Posthog.capture("signup", [distinct_id: "user_123"], DateTime.utc_now())

# Event with custom headers (e.g., for IP forwarding)
Posthog.capture("login", [distinct_id: "user_123"],
  [headers: [{"x-forwarded-for", "127.0.0.1"}]])

Feature Flags

PostHog feature flags can be used for feature management and A/B testing:

# Get all feature flags for a user
{:ok, flags} = Posthog.feature_flags("user_123")

# Check specific feature flag
{:ok, flag} = Posthog.feature_flag("new-dashboard", "user_123")

# Quick boolean check
if Posthog.feature_flag_enabled?("new-feature", "user_123") do
  # Show new feature
end

# Feature flags with group/person properties
Posthog.feature_flags("user_123",
  groups: %{company: "company_123"},
  group_properties: %{company: %{industry: "tech"}},
  person_properties: %{email: "user@example.com"}
)

Batch Processing

Multiple events can be sent in a single request for better performance:

events = [
  {"page_view", [distinct_id: "user_123"], nil},
  {"button_click", [distinct_id: "user_123", properties: %{button: "signup"}], nil}
]

Posthog.batch(events)

Each event in the batch is a tuple of {event_name, properties, timestamp}.

Summary

Functions

batch(events, opts \\ [])

Sends multiple events to PostHog in a single request.

capture(event, params, opts \\ [])

Captures an event in PostHog.

feature_flag(flag, distinct_id, opts \\ [])

Retrieves information about a specific feature flag for a given distinct ID.

feature_flag_enabled?(flag, distinct_id, opts \\ [])

Checks if a feature flag is enabled for a given distinct ID.

feature_flags(distinct_id, opts \\ [])

Retrieves all feature flags for a given distinct ID.

Functions

batch(events, opts \\ [])

@spec batch(
  [tuple()],
  keyword()
) :: result()

Sends multiple events to PostHog in a single request.

Parameters

events - List of event tuples in the format {event_name, properties, timestamp}
opts - Optional parameters for the batch request

Examples

events = [
  {"page_view", [distinct_id: "user_123"], nil},
  {"button_click", [distinct_id: "user_123", properties: %{button: "signup"}], nil}
]

Posthog.batch(events)

capture(event, params, opts \\ [])

@spec capture(atom() | String.t(), keyword() | map(), keyword() | timestamp()) ::
  result()

Captures an event in PostHog.

Parameters

event - The name of the event (string or atom)
params - Required parameters including :distinct_id and optional properties
opts - Optional parameters that can be either a timestamp or a keyword list of options

Options

:headers - Additional HTTP headers for the request
:groups - Group properties for the event
:group_properties - Additional properties for groups
:person_properties - Properties for the person
:timestamp - Custom timestamp for the event

Examples

# Basic event
Posthog.capture("page_view", distinct_id: "user_123")

# Event with properties
Posthog.capture("purchase", [
  distinct_id: "user_123",
  properties: %{
    product_id: "prod_123",
    price: 99.99
  }
])

# Event with timestamp
Posthog.capture("signup", [distinct_id: "user_123"], DateTime.utc_now())

# Event with custom headers
Posthog.capture("login", [distinct_id: "user_123"],
  [headers: [{"x-forwarded-for", "127.0.0.1"}]])

feature_flag(flag, distinct_id, opts \\ [])

@spec feature_flag(binary(), binary(), keyword()) :: result()

Retrieves information about a specific feature flag for a given distinct ID.

Parameters

flag - The name of the feature flag
distinct_id - The unique identifier for the user
opts - Optional parameters for the feature flag request

Examples

# Boolean feature flag
{:ok, flag} = Posthog.feature_flag("new-dashboard", "user_123")
# Returns: %Posthog.FeatureFlag{name: "new-dashboard", value: true, enabled: true}

# Multivariate feature flag
{:ok, flag} = Posthog.feature_flag("pricing-test", "user_123")
# Returns: %Posthog.FeatureFlag{
#   name: "pricing-test",
#   value: %{"price" => 99, "period" => "monthly"},
#   enabled: "variant-a"
# }

feature_flag_enabled?(flag, distinct_id, opts \\ [])

@spec feature_flag_enabled?(binary(), binary(), keyword()) :: boolean()

Checks if a feature flag is enabled for a given distinct ID.

This is a convenience function that returns a boolean instead of a result tuple. For multivariate flags, returns true if the flag has any value set.

Parameters

flag - The name of the feature flag
distinct_id - The unique identifier for the user
opts - Optional parameters for the feature flag request

Examples

if Posthog.feature_flag_enabled?("new-dashboard", "user_123") do
  # Show new dashboard
end

feature_flags(distinct_id, opts \\ [])

@spec feature_flags(
  binary(),
  keyword()
) :: result()

Retrieves all feature flags for a given distinct ID.

Parameters

distinct_id - The unique identifier for the user
opts - Optional parameters for the feature flag request

Options

:groups - Group properties for feature flag evaluation
:group_properties - Additional properties for groups
:person_properties - Properties for the person

Examples

# Basic feature flags request
{:ok, flags} = Posthog.feature_flags("user_123")

# With group properties
{:ok, flags} = Posthog.feature_flags("user_123",
  groups: %{company: "company_123"},
  group_properties: %{company: %{industry: "tech"}}
)