feat: Allow UUID to be set in events

This is a feature that exists in other libraries, so let's port it to Elixir as well

We're introducing some breaking changes here, so this will be merged on the v1 branch rather than `main`

Author: rafaeelaudibert

CHANGELOG.md

@@ -11,6 +11,7 @@
 - PostHog now requires you to initialize `Posthog.Application` alongside your supervisor tree. This is required because of our `Cachex` system to properly track your FF usage.
   - We'll also include local evaluation in the near term, which will also require a GenServer, therefore, requiring us to use a Supervisor.
 - Added `enabled_capture` configuration option to disable PostHog tracking in development/test environments
+- `Posthog.capture` now requires `distinct_id` as a required second argument
 
 ## 0.4.4 - 2025-04-14
 

MIGRATION.md

@@ -45,10 +45,35 @@ defmodule MyApp.Application do
 end
 ```
 
-#### Customizing the Cache (Optional)
+### `Posthog.capture` new signature
 
-By default, `Posthog.Application` starts a Cachex instance under the name `:posthog_feature_flag_cache`. You can override this by passing options:
+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:
 
 ```elixir
-{Posthog.Application, cache_name: :my_custom_cache}
+# 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"}]
+)
 ```

README.md

@@ -70,7 +70,7 @@ Add your PostHog configuration to your application's config:
 ```elixir
 # config/config.exs
 config :posthog,
-  api_url: "https://app.posthog.com",  # Or your self-hosted PostHog instance URL
+  api_url: "https://us.posthog.com",  # Or `https://eu.posthog.com` or your self-hosted PostHog instance URL
   api_key: "phc_your_project_api_key"
 
 # Optional configurations
@@ -116,29 +116,29 @@ config :posthog,
 Simple event capture:
 
 ```elixir
-# Basic event
-Posthog.capture("page_view", distinct_id: "user_123")
+# Basic event with `event` and `distinct_id`, both required
+Posthog.capture("page_view", "user_123")
 
 # Event with properties
-Posthog.capture("purchase", [
-  distinct_id: "user_123",
-  properties: %{
+Posthog.capture("purchase", "user_123", %{
     product_id: "prod_123",
     price: 99.99,
     currency: "USD"
-  }
-])
+})
 
 # Event with custom timestamp
-Posthog.capture("signup_completed",
-  [distinct_id: "user_123"],
-  DateTime.utc_now()
-)
+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",
-  [distinct_id: "user_123"],
-  [headers: [{"x-forwarded-for", "127.0.0.1"}]]
+Posthog.capture(
+  "login",
+  "user_123",
+  %{},
+  headers: [{"x-forwarded-for", "127.0.0.1"}]
 )
 ```
 
@@ -148,8 +148,8 @@ Send multiple events in a single request:
 
 ```elixir
 events = [
-  {"page_view", [distinct_id: "user_123"], nil},
-  {"button_click", [distinct_id: "user_123", properties: %{button_id: "signup"}], nil}
+  {"page_view", "user_123", %{}},
+  {"button_click", "user_123", %{button_id: "signup"}}
 ]
 
 Posthog.batch(events)

lib/posthog.ex

@@ -60,18 +60,17 @@ defmodule Posthog do
       Posthog.capture("page_view", distinct_id: "user_123")
 
       # Event with properties
-      Posthog.capture("purchase", [
+      Posthog.capture("purchase", %{
         distinct_id: "user_123",
         product_id: "prod_123",
         price: 99.99
-      ])
+      })
 
       # Event with custom timestamp
-      Posthog.capture("signup", [distinct_id: "user_123"], DateTime.utc_now())
+      Posthog.capture("signup", "user_123", %{}, timestamp: 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"}]])
+      Posthog.capture("login", "user_123", %{}, headers: [{"x-forwarded-for", "127.0.0.1"}])
 
   ## Feature Flags
 
@@ -129,24 +128,21 @@ defmodule Posthog do
   ## Examples
 
       # Basic event
-      Posthog.capture("page_view", distinct_id: "user_123")
+      Posthog.capture("page_view", "user_123")
 
       # Event with properties
-      Posthog.capture("purchase", [
-        distinct_id: "user_123",
+      Posthog.capture("purchase", "user_123", %{
         product_id: "prod_123",
         price: 99.99
-      ])
+      })
 
       # Event with timestamp
-      Posthog.capture("signup", [distinct_id: "user_123"], DateTime.utc_now())
+      Posthog.capture("signup", "user_123", %{}, timestamp: DateTime.utc_now())
 
       # Event with custom headers
-      Posthog.capture("login", [distinct_id: "user_123"],
-        [headers: [{"x-forwarded-for", "127.0.0.1"}]])
+      Posthog.capture("login", "user_123", %{}, headers: [{"x-forwarded-for", "127.0.0.1"}])
   """
   @typep result() :: {:ok, term()} | {:error, term()}
-  @typep timestamp() :: DateTime.t() | NaiveDateTime.t() | String.t() | nil
   @typep cache_key() :: {:feature_flag_called, binary(), binary()}
   @typep feature_flag_called_event_properties_key() ::
            :"$feature_flag"
@@ -162,22 +158,23 @@ defmodule Posthog do
 
   alias Posthog.{Client, FeatureFlag}
 
-  @spec capture(atom() | String.t(), keyword() | map(), keyword() | timestamp()) :: result()
-  defdelegate capture(event, params, opts \\ []), to: Client
+  @spec capture(Client.event(), Client.distinct_id(), Client.properties(), Client.opts()) ::
+          result()
+  defdelegate capture(event, distinct_id, properties, opts \\ []), to: Client
 
   @doc """
   Sends multiple events to PostHog in a single request.
 
   ## Parameters
 
-    * `events` - List of event tuples in the format `{event_name, properties, timestamp}`
+    * `events` - List of event tuples in the format `{event_name, distinct_id, properties}`
     * `opts` - Optional parameters for the batch request
 
   ## Examples
 
       events = [
-        {"page_view", [distinct_id: "user_123"], nil},
-        {"button_click", [distinct_id: "user_123", button: "signup"], nil}
+        {"page_view", "user_123", %{}},
+        {"button_click", "user_123", %{button: "signup"}}
       ]
 
       Posthog.batch(events)
@@ -244,8 +241,8 @@ defmodule Posthog do
       if Keyword.get(opts, :send_feature_flag_event, true),
         do:
           capture_feature_flag_called_event(
+            distinct_id,
             %{
-              "distinct_id" => distinct_id,
               "$feature_flag" => flag,
               "$feature_flag_response" => enabled
             },
@@ -259,21 +256,25 @@ defmodule Posthog do
     end
   end
 
-  @spec capture_feature_flag_called_event(feature_flag_called_event_properties(), map()) ::
+  @spec capture_feature_flag_called_event(
+          Client.distinct_id(),
+          feature_flag_called_event_properties(),
+          map()
+        ) ::
           :ok
-  defp capture_feature_flag_called_event(properties, response) do
+  defp capture_feature_flag_called_event(distinct_id, properties, response) do
     # Create a unique key for this distinct_id and flag combination
-    cache_key = {:feature_flag_called, properties["distinct_id"], properties["$feature_flag"]}
+    cache_key = {:feature_flag_called, distinct_id, properties["$feature_flag"]}
 
     # Check if we've seen this combination before using Cachex
     case Cachex.exists?(Posthog.Application.cache_name(), cache_key) do
       {:ok, false} ->
-        do_capture_feature_flag_called_event(cache_key, properties, response)
+        do_capture_feature_flag_called_event(cache_key, distinct_id, properties, response)
 
       # Should be `{:error, :no_cache}` but Dyalixir is wrongly assuming that doesn't exist
       {:error, _} ->
         # Cache doesn't exist, let's capture the event PLUS notify user they should be initing it
-        do_capture_feature_flag_called_event(cache_key, properties, response)
+        do_capture_feature_flag_called_event(cache_key, distinct_id, properties, response)
 
         Logger.error("""
         [posthog] Cachex process `#{inspect(Posthog.Application.cache_name())}` is not running.
@@ -299,10 +300,11 @@ defmodule Posthog do
 
   @spec do_capture_feature_flag_called_event(
           cache_key(),
+          Client.distinct_id(),
           feature_flag_called_event_properties(),
           map()
         ) :: :ok
-  defp do_capture_feature_flag_called_event(cache_key, properties, response) do
+  defp do_capture_feature_flag_called_event(cache_key, distinct_id, properties, response) do
     flag = properties["$feature_flag"]
 
     properties =
@@ -324,7 +326,7 @@ defmodule Posthog do
       end
 
     # Send the event to our server
-    Client.capture("$feature_flag_called", properties, [])
+    Client.capture("$feature_flag_called", distinct_id, properties, [])
 
     # Add new entry to cache using Cachex
     Cachex.put(Posthog.Application.cache_name(), cache_key, true)