Mxpanel (Mxpanel v1.0.1) View Source

Client for Mixpanel Ingestion API.

It provides a sync API that makes HTTP request to the Mixpanel API. And also a async API that buffers and delivers the buffered events to Mixpanel in background.

Checkout the documentation for more information.

Installation

The package can be installed by adding mxpanel to your list of dependencies in mix.exs:

def deps do
  [
    {:mxpanel, "~> 1.0.1"},
    {:jason, "~> 1.2"},
    {:hackney, "~> 1.17"}
  ]
end

Examples

# Create a client struct with your project token
client = %Mxpanel.Client{token: "<mixpanel project token>"}

# track an event
"signup"
|> Mxpanel.track("billybob")
|> Mxpanel.deliver(client)

# track an event with optional properties
"signup"
|> Mxpanel.track("billybob", %{"Favourite Color" => "Red"})
|> Mxpanel.deliver(client)

# set an IP address to get automatic geolocation info
"signup"
|> Mxpanel.track("billybob", %{}, ip: "72.229.28.185")
|> Mxpanel.deliver(client)

# track an event with a specific timestamp
"signup"
|> Mxpanel.track("billybob", %{}, time: System.os_time(:second) - 60)
|> Mxpanel.deliver(client)

# track an event in background, the event will be buffered, and later sent in batches
Mxpanel.Batcher.start_link(name: MyApp.Batcher, token: "<mixpanel project token>")

"signup"
|> Mxpanel.track("billybob")
|> Mxpanel.deliver_later(MyApp.MxpanelBatcher)

Checkout the documentation for complete usage and available functions.

Telemetry

Mxpanel currently exposes following Telemetry events:

[:mxpanel, :batcher, :buffers_info] - Dispatched periodically by each running batcher exposing the size of each running buffer per endpoint in the pool.
- Measurement: %{}
- Metadata: %{batcher_name: atom(), buffer_sizes: %{atom() => [integer()]}}

Changelog

See the changelog.

Link to this section Summary

Functions

create_alias(distinct_id, alias_id)

Creates an alias for an existing distinct id.

deliver(operation_or_operations, client)

Delivers an operation to the mixpanel API using the configured HTTP client.

deliver_later(operation_or_operations, batcher_name)

Enqueues an operation. The operation will be stored in a buffer and sent in batches to mixpanel.

json_library()

Returns the configured JSON encoding library for Mxpnale (defaults to Jason).

track(name, distinct_id, additional_properties \\ %{}, opts \\ [])

Tracks an event.

Link to this section Functions

create_alias(distinct_id, alias_id)

Specs

create_alias(String.t(), String.t()) :: Mxpanel.Operation.t()

Creates an alias for an existing distinct id.

"distinct_id"
|> Mxpanel.create_alias("your_alias")
|> Mxpanel.deliver()

deliver(operation_or_operations, client)

Specs

deliver(Mxpanel.Operation.t() | [Mxpanel.Operation.t()], Mxpanel.Client.t()) ::
  :ok | {:error, term()}

Delivers an operation to the mixpanel API using the configured HTTP client.

Mxpanel.deliver(operation, client)
Mxpanel.deliver([operation_1, operation_2], client)

deliver_later(operation_or_operations, batcher_name)

Specs

deliver_later(
  Mxpanel.Operation.t() | [Mxpanel.Operation.t()],
  Mxpanel.Batcher.name()
) :: :ok

Enqueues an operation. The operation will be stored in a buffer and sent in batches to mixpanel.

Mxpanel.Batcher.start_link(name: MyApp.MxpanelBatcher, token: "mixpanel project token")

"signup"
|> Mxpanel.track("13793")
|> Mxpanel.deliver_later(MyApp.MxpanelBatcher)

Sending multiple operations:

operation_1 = Mxpanel.track("signup", "13793")
operation_2 = Mxpanel.track("first login", "13793")

Mxpanel.deliver_later([operation_1, operation_2], MyApp.MxpanelBatcher)

Why use it?

HTTP requests to the Mixpanel API often take time and may fail. If you are tracking events during a web request, you probably, don't want to make your users wait the extra time for the mixpanel API call to finish. The batcher will enqueue the operations, send them in batches to mixpanel with automatic retries.

Checkout Mxpanel.Batcher for more information.

json_library()

Specs

json_library() :: module()

Returns the configured JSON encoding library for Mxpnale (defaults to Jason).

To customize the JSON library, including the following in your config/config.exs:

config :mxpanel, :json_library, Jason

track(name, distinct_id, additional_properties \\ %{}, opts \\ [])

Specs

track(String.t(), String.t(), map(), Keyword.t()) :: Mxpanel.Operation.t()

Tracks an event.

"signup"
|> Mxpanel.track("13793")
|> Mxpanel.deliver()

"signup"
|> Mxpanel.track("13793")
|> Mxpanel.deliver()

"signup"
|> Mxpanel.track("13793", %{"Favourite Color" => "Red"})
|> Mxpanel.deliver()

"signup"
|> Mxpanel.track("13793", %{}, ip: "72.229.28.185")
|> Mxpanel.deliver()

"signup"
|> Mxpanel.track("13793", %{}, time: 1624811298)
|> Mxpanel.deliver()

Options

:time - Specific timestamp in seconds of the event. Defaults to System.os_time(:second).
:ip - IP address to get automatic geolocation info.