PostHog (posthog v2.0.0)

Main API for working with PostHog

Summary

Types

distinct_id()

string representing distinct ID

event()

Event name, such as "user_signed_up" or "$create_alias"

properties()

Map representing event properties.

supervisor_name()

Name under which an instance of PostHog supervision tree is registered.

Functions

bare_capture(name \\ __MODULE__, event, distinct_id, properties \\ %{})

Captures a single event without retrieving properties from context.

capture(name \\ __MODULE__, event, properties \\ %{})

Captures a single event.

config(name \\ __MODULE__)

Returns the configuration map for a named PostHog supervisor.

get_context(name \\ __MODULE__)

Retrieves context for the current process.

get_event_context(name \\ __MODULE__, event)

Retrieves context for the current process scoped to a specific event.

set_context(name \\ __MODULE__, context)

Sets context for the current process.

set_event_context(name \\ __MODULE__, event, context)

Sets context for the current process scoped to a specific event.

Types

distinct_id()

@type distinct_id() :: String.t()

string representing distinct ID

event()

@type event() :: String.t()

Event name, such as "user_signed_up" or "$create_alias"

properties()

@type properties() :: %{optional(String.t()) => any(), optional(atom()) => any()}

Map representing event properties.

Note that it must be JSON-serializable.

supervisor_name()

@type supervisor_name() :: atom()

Name under which an instance of PostHog supervision tree is registered.

Functions

bare_capture(name \\ MODULE, event, distinct_id, properties \\ %{})

@spec bare_capture(supervisor_name(), event(), distinct_id(), properties()) :: :ok

Captures a single event without retrieving properties from context.

Capture is a relatively lightweight operation. The event is prepared synchronously and then sent to PostHog workers to be batched together with other events and sent over the wire.

Examples

Capture a simple event:

PostHog.bare_capture("event_captured", "user123")

Capture an event with properties:

PostHog.bare_capture("event_captured", "user123", %{backend: "Phoenix"})

Capture through a named PostHog instance:

PostHog.bare_capture(MyPostHog, "event_captured", "user123")

capture(name \\ MODULE, event, properties \\ %{})

@spec capture(supervisor_name(), event(), properties()) ::
  :ok | {:error, :missing_distinct_id}

Captures a single event.

Any context previously set will be included in the event properties. Note that distinct_id is still required.

Examples

Set context and capture an event:

PostHog.set_context(%{distinct_id: "user123", "$feature/my-feature-flag": true})
PostHog.capture("job_started", %{job_name: "JobName"})

Set context and capture an event through a named PostHog instance:

PostHog.set_context(MyPostHog, %{distinct_id: "user123", "$feature/my-feature-flag": true})
PostHog.capture(MyPostHog, "job_started", %{job_name: "JobName"})

config(name \\ MODULE)

@spec config(supervisor_name()) :: PostHog.Config.config()

Returns the configuration map for a named PostHog supervisor.

Examples

Retrieve the default PostHog instance config:

%{supervisor_name: PostHog} = PostHog.config()

Retrieve named instance config:

%{supervisor_name: MyPostHog} = PostHog.config(MyPostHog)

get_context(name \\ MODULE)

@spec get_context(supervisor_name()) :: properties()

Retrieves context for the current process.

Examples

Set and retrieve context for current process:

> PostHog.set_context(%{foo: "bar"})
> PostHog.get_context()
%{foo: "bar"}

Set and retrieve context for a named PostHog instance:

> PostHog.set_context(MyPostHog, %{foo: "bar"})
> PostHog.get_context(MyPostHog)
%{foo: "bar"}

get_event_context(name \\ MODULE, event)

Retrieves context for the current process scoped to a specific event.

Examples

Set and retrieve context scoped to an event:

> PostHog.set_event_context("$exception", %{foo: "bar"})
> PostHog.get_event_context("$exception")
%{foo: "bar"}

Set and retrieve context for a specific event through a named PostHog instance:

> PostHog.set_event_context(MyPostHog, "$exception", %{foo: "bar"})
> PostHog.get_event_context(MyPostHog, "$exception")
%{foo: "bar"}

set_context(name \\ MODULE, context)

@spec set_context(supervisor_name(), properties()) :: :ok

Sets context for the current process.

Examples

Set and retrieve context for the current process:

> PostHog.set_context(%{foo: "bar"})
> PostHog.get_context()
%{foo: "bar"}

Set and retrieve context for a named PostHog instance:

> PostHog.set_context(MyPostHog, %{foo: "bar"})
> PostHog.get_context(MyPostHog)
%{foo: "bar"}

set_event_context(name \\ MODULE, event, context)

@spec set_event_context(supervisor_name(), event(), properties()) :: :ok

Sets context for the current process scoped to a specific event.

Examples

Set and retrieve context scoped to an event:

> PostHog.set_event_context("$exception", %{foo: "bar"})
> PostHog.get_event_context("$exception")
%{foo: "bar"}

Set and retrieve context for a specific event through a named PostHog instance:

> PostHog.set_event_context(MyPostHog, "$exception", %{foo: "bar"})
> PostHog.get_event_context(MyPostHog, "$exception")
%{foo: "bar"}