Mxpanel (Mxpanel v0.3.0) View Source

Client for Mixpanel Ingestion API.

Hex.pm Version CI Coverage Status

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, "~> 0.3.0"},
    {: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
event = Mxpanel.Event.new("signup", "billybob")
Mxpanel.track(client, event)

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

# set an IP address to get automatic geolocation info
event = Mxpanel.Event.new("signup", "billybob", %{}, ip: "72.229.28.185")
Mxpanel.track(client, event)

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

# 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>")
event = Mxpanel.Event.new("signup", "billybob")
Mxpanel.track_later(MyApp.MxpanelBatcher, event)

# Create an alias for an existing distinct id
Mxpanel.create_alias(client, "distinct_id", "your_alias")

# create or update a user in Mixpanel Engage
properties = %{"Address" => "1313 Mockingbird Lane", "Birthday" => "1948-01-01"}
Mxpanel.People.set(client, "billybob", properties)

# create or update a user in Mixpanel Engage without altering $last_seen
Mxpanel.People.set(client, "billybob", %{plan: "premium"}, ignore_time: true)

# set a user profile's IP address to get automatic geolocation info
Mxpanel.People.set(client, "billybob", %{plan: "premium"}, ip: "72.229.28.185")

# set properties on a user, don't override
properties = %{"First login date" => "2013-04-01T13:20:00"}
Mxpanel.People.set_once(client, "billybob", properties)

# removes the properties
Mxpanel.People.unset(client, "billybob", ["Address", "Birthday"])

# increment a numeric property
Mxpanel.People.increment(client, "billybob", "Number of Logins", 12)

# append value to a list
Mxpanel.People.append_item(client, "billybob", "Items purchased", "socks")

# remove value from a list
Mxpanel.People.remove_item(client, "billybob", "Items purchased", "t-shirt")

# delete a user
Mxpanel.People.delete(client, "billybob")

Telemetry

Mxpanel currently exposes following Telemetry events:

  • [:mxpanel, :batcher, :buffers_info] - Dispatched periodically by each running batcher exposing the size of each running buffer in the pool.

    • Measurement: %{}
    • Metadata: %{batcher_name: atom(), buffer_sizes: [integer()]}

Changelog

See the changelog.

Link to this section Summary

Functions

Creates an alias for an existing distinct id.

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

Send a single event into Mixpanel.

Enqueues the event. The event will be store in a buffer and sent in batches to mixpanel.

Link to this section Functions

Link to this function

create_alias(client, distinct_id, alias_id)

View Source

Specs

create_alias(Mxpanel.Client.t(), String.t(), String.t()) ::
  :ok | {:error, term()}

Creates an alias for an existing distinct id.

Mxpanel.create_alias(client, "distinct_id", "your_alias")

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
Link to this function

track(client, event_or_events)

View Source

Specs

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

Send a single event into Mixpanel.

client = %Mxpanel.Client{token: "mixpanel project token"}
event = Mxpanel.Event.new("signup", "123")
Mxpanel.track(client, event)

Import a batch of events into Mixpanel.

client = %Mxpanel.Client{token: "mixpanel project token"}
event_1 = Mxpanel.Event.new("signup", "123")
event_2 = Mxpanel.Event.new("signup", "456")

Mxpanel.track(client, [event_1, event_2])
Link to this function

track_later(batcher_name, event_or_events)

View Source

Specs

track_later(Mxpanel.Batcher.name(), Mxpanel.Event.t() | [Mxpanel.Event.t()]) ::
  :ok

Enqueues the event. The event will be store in a buffer and sent in batches to mixpanel.

Mxpanel.Batcher.start_link(name: MyApp.MxpanelBatcher, token: "mixpanel project token")
event = Mxpanel.Event.new("signup", "123")

Mxpanel.track_later(MyApp.MxpanelBatcher, event)

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.

Checkout Mxpanel.Batcher for more information.