README.md

MixpanelPlug

A plug-based approach to Mixpanel tracking with Elixir. Use MixpanelPlug to:

• Track events with useful context like referrer, user agent information, and UTM properties
• Keep user profiles up to date on every request

MixpanelPlug respects the ‘Do Not Track’ request header. When this is set, no tracking calls will be made.

Installation

If available in Hex, the package can be installed by adding mixpanel_plug to your list of dependencies in mix.exs:

def deps do
  [
    {:mixpanel_plug, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/mixpanel_plug.

Configuration

Add configuration for mixpanel_api_ex to your config/config.exs file:

config :mixpanel_api_ex, config: [token: "your_mixpanel_token"]

Usage

In a Phoenix application, register the MixpanelPlug plug in router.ex:

defmodule Example.Router do
  use Example, :router

  pipeline :browser do
    plug :accepts, ["html", "json"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug :put_secure_browser_headers
+   plug MixpanelPlug
  end
end

If the ‘Do Not Track’ (dnt) has been set to 1, the property do_not_track: true will be assigned to the connection. Additionally, a call to MixpanelPlug.update_profile/2 will be made with the value of current_user from the connection, if ‘Do Not Track’ is not set. For more information, please see the module documentation.

For making tracking calls, use MixpanelPlug.track_event:

defmodule Example.UserController do
  use Example, :controller

  import MixpanelPlug, only: [track_event: 3]

  def create(conn, %{"email" => email}) do
    conn
    |> track_event("Example User Created", %{"email" => email})
    |> render("user_created.html")
  end
end

The properties added to the tracking call include the following, where appropriate:

%{
  "email" => "[email protected]",
  "Current Path" => "/users",
  "$browser" => "Mobile Safari",
  "$browser_version" => "10.0",
  "$device" => "iPhone",
  "$os" => "iOS 10.3.1",
  "utm_campaign" => "campaign",
  "utm_content" => "content",
  "utm_medium" => "medium",
  "utm_source" => "source",
  "utm_term" => "term"
}