# `PostHog`
[🔗](https://github.com/posthog/posthog-elixir/blob/v2.18.0/lib/posthog.ex#L1)

Main API for working with PostHog

# `distinct_id`

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

String representing a PostHog distinct ID.

# `event`

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

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

# `properties`

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

Map representing event properties.

Note that it __must__ be JSON-serializable.

# `supervisor_name`

```elixir
@type supervisor_name() :: atom()
```

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

# `bare_capture`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@spec get_event_context(supervisor_name(), event()) :: properties()
```

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`

```elixir
@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`

```elixir
@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"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*