Migration

This is a migration guide for all major version bumps

v1 -> v2

Version 2.0 is a whole new library, so we encourage you to use this upgrade as an opportunity to revisit your PostHog usage in your application. Even the root level module was renamed from Posthog to PostHog.

Configuration

Configuration has been completely reworked. We advise you to remove your existing configuration and follow Getting Started section for setup.

Event Capture

PostHog.capture signature has changed. It now accepts properties only as a map. distinct_id is now included in the properties.

PostHog.capture("user_signed_up", %{
  distinct_id: "distinct_id_of_the_user",
  login_type: "email",
  is_free_trial: true
})

No additional options can be passed. PostHog now automatically offloads events to a pool of sender workers that will batch and send your events. This also means that Posthog.batch doesn't exist anymore and you should simply call capture/2 for each of your events.

Feature Flags

Posthog.feature_flag and Posthog.feature_flag_enabled functions were replaced with PostHog.FeatureFlags module. Check its docs for the new usage guidelines.

v0 -> v1

When we stabilized our library, we decided to pull some breaking changes.

Minimum Elixir version bumped to v1.14

The library previously supported Elixir v1.12+. You'll need to migrate to Elixir v1.14 - at least. Elixir v1.14 was launched more than 2.5 years ago, and we believe that should be enough time for you to migrate. You can check Elixir's own release announcements to understand how you should proceed with the migration.

• https://elixir-lang.org/blog/2021/12/03/elixir-v1-13-0-released/
• https://elixir-lang.org/blog/2022/09/01/elixir-v1-14-0-released/

Decide v4 - Feature Flags

PostHog is consistently upgrading our internal data representation so that it's better for users each and every time. We've recently launched a new version of our /decide endpoint called v4. This endpoint is slightly different, which caused a small change in behavior for our flags.

PostHog.FeatureFlag previously included a key value to represent the internal structure of a flag. It was renamed to payload to:

1. better represent the fact that it can be both an object and a boolean
2. align it more closely with our other SDKs

PostHog.Application

This library now depends on Cachex, and includes a supervision tree. There are 2 options:

1. If you have a simple application without a YourApp.Application application, then you can simply add :posthog to your mix.exs application definition

def application do
    [
      extra_applications: [
        # ... your existing applications ...
        :posthog
      ],
    ]
  end

2. Or, if you're already using an Application, you can add Posthog.Application to your own supervision tree:

# lib/my_app/application.ex
defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # Your other children...
      {PostHog.Application, []}
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

PostHog.capture new signature

The signature to PostHog.capture has changed. distinct_id is now a required argument.

Here are some examples on how the method is now used:

# Basic event with `event` and `distinct_id`, both required
PostHog.capture("page_view", "user_123")

# Event with properties
PostHog.capture("purchase", "user_123", %{
    product_id: "prod_123",
    price: 99.99,
    currency: "USD"
})

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

# Event with custom UUID
uuid = "..."
PostHog.capture("signup_completed", "user_123", %{}, uuid: uuid)

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