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)
  enabled_capture: true  # Whether to enable PostHog tracking (optional, defaults to true)
                         # Set to false in development/test environments to disable tracking

Disabling PostHog

You can disable PostHog tracking by setting enabled: false in your configuration. This is particularly useful in development or test environments where you don't want to send actual events to PostHog.

When enabled_capture is set to false:

• All Posthog.capture/3 and Posthog.batch/2 calls will succeed silently
• PostHog will still communicate with the server for Feature Flags

This is useful for:

• Development and test environments where you don't want to pollute your PostHog instance
• Situations where you need to temporarily disable tracking

Example configuration for development:

# config/dev.exs
config :posthog,
  enabled_capture: false  # Disable tracking in development

Example configuration for test:

# config/test.exs
config :posthog,
  enabled_capture: false  # Disable tracking in test environment

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",
  product_id: "prod_123",
  price: 99.99
})

# Event with custom timestamp
Posthog.capture("signup", "user_123", %{}, timestamp: DateTime.utc_now())

# Event with custom headers (e.g., for IP forwarding)
Posthog.capture("login", "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", button: "signup"], nil}
]

Posthog.batch(events)

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