Giter VIP home page Giter VIP logo

mixpanel_api_ex's Introduction

Mixpanel

Module Version Hex Docs Total Downloads License Last Updated Coverage Status CI

This is a non-official third-party Elixir client for the Mixpanel.

Note that this README refers to the master branch of mixpanel_api_ex, not the latest released version on Hex. See the documentation for the documentation of the version you're using.

For the list of changes, checkout the latest release notes.

Installation

Add mixpanel_api_ex to your list of dependencies in mix.exs.

def deps do
  [
    {:mixpanel_api_ex, "~> 1.2"},

    # optional, but recommended adapter
    {:hackney, "~> 1.20"}
  ]
end

The default adapter is Erlang's built-in httpc, but it is not recommended to use it in a production environment as it does not validate SSL certificates among other issues.

And ensure that mixpanel_api_ex is started before your application:

def application do
  [applications: [:mixpanel_api_ex, :my_app]]
end

Usage Example

Define an interface module with use Mixpanel.

# lib/my_app/mixpanel.ex

defmodule MyApp.Mixpanel do
  use Mixpanel
end

Configure the interface module in config/config.exs.

# config/config.exs

config :mixpanel_api_ex, MyApp.Mixpanel,
  project_token: System.get_env("MIXPANEL_PROJECT_TOKEN")

And then to track an event:

MyApp.Mixpanel.track("Signed up", %{"Referred By" => "friend"}, distinct_id: "13793")
# => :ok

TOC

Configuration

EU Data Residency

By default mixpanel_api_ex sends data to Mixpanels's US Servers. However, this can be changes via :base_url parameter:

# config/config.exs

config :mixpanel_api_ex, MyApp.Mixpanel,
  base_url: "https://api-eu.mixpanel.com",
  project_token: System.get_env("MIXPANEL_PROJECT_TOKEN")

:base_url is not limited specifically to this URL. So if you need you can provide an proxy address to route Mixpanel events via.

Supported HTTP clients

At the moment httpc and hackney libraries are supported. :http_adapter param can be used to select which HTTP adapter you want to use.

# config/config.exs

config :mixpanel_api_ex, MyApp.Mixpanel,
  http_adapter: Mixpanel.HTTP.Hackney,
  project_token: System.get_env("MIXPANEL_PROJECT_TOKEN")

The default adapter is Erlang's built-in httpc, but it is not recommended to use it in a production environment as it does not validate SSL certificates among other issues.

Running multiple instances

You can configure multiple instances to be used by different applications within your VM. For instance the following example demonstrates having separate client which is used specifically to sending data to Mixpanel's EU servers.

# config/config.exs

config :mixpanel_api_ex, MyApp.Mixpanel,
  project_token: System.get_env("MIXPANEL_PROJECT_TOKEN")

config :mixpanel_api_ex, MyApp.Mixpanel.EU,
  base_url: "https://api-eu.mixpanel.com",
  project_token: System.get_env("MIXPANEL_EU_PROJECT_TOKEN")
# lib/my_app/mixpanel.ex

defmodule MyApp.Mixpanel do
  use Mixpanel
end
# lib/my_app/mixpanel_eu.ex

defmodule MyApp.MixpanelEU do
  use Mixpanel
end

Running tests

Other than not running mixpanel_api_ex application in test environment you have got two other options. Which one you need to use depends on if you want the client process running or not.

If you prefer the client process to be up and running during the test suite running you may provide Mixpanel.HTTP.NoOp adapter to :http_adapter param. As the adapter's name suggests it won't do any actual work sending data to Mixpanel, but everything else will be running (including emitting Telemetry's event).

# config/test.exs

config :mixpanel_api_ex, MyApp.Mixpanel,
  project_token: "",
  http_adapter: Mixpanel.HTTP.NoOp

The second options would be simply assign nil as configuration value. This way that client won't be started by the application supervisor.

# config/test.exs

config :mixpanel_api_ex, MyApp.Mixpanel, nil

Runtime/Dynamic Configuration

In cases when you don't know upfront how many client instances you need and what project tokens to use (for instance this information is read from a database or a external configuration file during application startup) you can use Mixpanel.start_client/1 and Mixpanel.terminate_client/1 to manually run and kill instances when needed.

For instance this would start MyApp.Mixpanel.US named client with "token" project token:

Mixpanel.start_client(Mixpanel.Config.client!(MyApp.Mixpanel.US, [project_token: "token"])
# => {:ok, #PID<0.123.0>}

Mixpanel.Config.client!/2 makes sure that provided parameters are correct.

And when you done with it, this function would stop the client immediately:

Mixpanel.terminate_client(MyApp.Mixpanel.US)
# => :ok

To make it possible to call this client process you might want to use some macro magic, which would compile a new module in runtime:

ast =
  quote do
    use Mixpanel
  end

Module.create(MyApp.Mixpanel.US, ast, Macro.Env.location(__ENV__))
# => {:module, _module, _bytecode, _exports}

If creating a module is not a case, you still can call the client's process directly (it's a GenServer after all). For instance:

Client.track(MyApp.Mixpanel.US, event, properties, opts)
# => :ok

Usage

Tracking events

Use Mixpanel.track/3 function to track events:

MyApp.Mixpanel.track(
  "Signed up",
  %{"Referred By" => "friend"},
  distinct_id: "13793"
)
# => :ok

The time an event occurred and IP address of an user can be provided via opts:

MyApp.Mixpanel.track(
  "Level Complete",
  %{"Level Number" => 9},
  distinct_id: "13793",
  time: ~U[2013-01-15 00:00:00Z],
  ip: "203.0.113.9"
)
# => :ok

Tracking profile updates

Use Mixpanel.engage/3,4 function to track profile updates:

MyApp.Mixpanel.engage(
  "13793",
  "$set",
  %{"Address" => "1313 Mockingbird Lane"}
)
# => :ok

The time an event occurred and IP address of an user can be provided via opts:

MyApp.Mixpanel.engage(
  "13793",
  "$set",
  %{"Birthday" => "1948-01-01"},
  time: ~U[2013-01-15 00:00:00Z],
  ip: "123.123.123.123"
)
# => :ok

Mixpanel.engage/2 works with batches:

MyApp.Mixpanel.engage(
  [
    {"13793", "$set", %{"Address" => "1313 Mockingbird Lane"}},
    {"13793", "$set", %{"Birthday" => "1948-01-01"}}
  ],
  ip: "123.123.123.123"
)
# => :ok

Merging two profiles

Use Mixpanel.create_alias/2 create an alias for a district ID, effectively merging two profiles:

MyApp.Mixpanel.create_alias("13793", "13794")
# => :ok

Telemetry

mixpanel_api_ex uses Telemetry to provide instrumentation. See the Mixpanel.Telemetry module for details on specific events.

Contributing

  1. Fork it (https://github.com/asakura/mixpanel_api_ex/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Test your changes by running unit tests and property based tests (mix t && mix p)
  4. Check that provided changes does not have type errors (mix dialyzer)
  5. Additionally you might run Gradient to have extra insight into type problems (mix gradient)
  6. Make sure that code is formatted (mix format)
  7. Run Credo to make sure that there is no code readability/maintainability issues (mix credo --strict)
  8. Commit your changes (git commit -am 'Add some feature')
  9. Push to the branch (git push origin my-new-feature)
  10. Create new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details

Copyright (c) 2016-2023 Mikalai Seva

mixpanel_api_ex's People

Contributors

asakura avatar bobishh avatar dependabot[bot] avatar ephe-meral avatar kelvinst avatar michaelst avatar san650 avatar vitaly-a-ivanov avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

mixpanel_api_ex's Issues

UndefinedFunctionError) function Poison.encode!/1 is undefined (module Poison is not available)

GenServer Mixpanel.Client terminating
2022-08-11T22:41:32.879434747Z ** (UndefinedFunctionError) function Poison.encode!/1 is undefined (module Poison is not available)

Seeing this in prod environments but not dev. The mix.lock file lists poison:

  "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [:mix], [], "hexpm", "fec8660eb7733ee4117b85f55799fd3833eb769a6df71ccf8903e8dc5447cfce"},

I'm using application inference and there's nothing explicitly set for applications in mix.exs.

Any ideas?

Enhancement Request: Support for Sending Data to Multiple Mixpanel Projects

I would like to request an enhancement to the mixpanel_api_ex library to support sending data to multiple Mixpanel projects based on specific criteria. Currently, the library is designed to interact with a single Mixpanel project using a configured token.

Use Case:
In certain scenarios, it is necessary to send data to different Mixpanel projects based on the data itself, such as distinguishing between projects for different clients or segments.

Requested Functionality:
This enhancement request aims to enable the library to send data to multiple Mixpanel projects simultaneously. Ideally, this functionality would allow developers to configure and manage multiple instances of the mixpanel_api_ex client, each with its own Mixpanel project token, and direct data to the appropriate instance based on specific criteria, such as the data content.

Example:
A potential use case is an application that serves multiple clients, and each client has its own Mixpanel project. Based on the client associated with a user’s action, the application should send the data to the corresponding Mixpanel project.

config :mixpanel_api_ex, :config,
   project_name: : project_one,
   project_token: "<Put Project Token here>",
   active: true
   
config :mixpanel_api_ex, :config,
   project_name: : project_two,
   project_token: "<Put Project Token here>",
   active: true
   
   
Mixpanel.track(: project_one, event, properties, opts)
Mixpanel.track(: project_two, event, properties, opts)

Performance and resource implications:
Providing the ability to manage multiple Mixpanel clients should be done in a way that is efficient and does not introduce significant overhead.

Please consider this enhancement request to make the mixpanel_api_ex library even more versatile for handling diverse use cases involving multiple Mixpanel projects. πŸš€

Thank you for your attention to this request.

Multiple mixpanel projects on the fly

hi!

First of all thanks for your library, it is awesome!

I saw your recent changes supporting multiple mixpanel projects but we have a use case not covered. We don't know on compile time the projects we will send events, instead we read from a source the mixpanel token.

It would be great if the opts parameter in the track function accepts a token option, so if it exists use it, if not use the one in the gen_server's state.

does it make sense? If you like the idea I can open a PR.

Thanks

Switch to Jason

Hi! The Elixir community has pretty much completely switched to Jason as the preferred json library these days (Poison hasn't had a release since 2018). Can we please get a new release of mixpanel_api_ex with Jason instead of Poison?

Config File

You might update the documentation to this for the config:

config :mixpanel_api_ex, :config,
  active: true,
  token: ""

Instead of what you had. (took me a whlie to figure this out)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.