mengpaneel 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d269ce3a419815bff9e35c98f2cd9c51d61ae77
+  data.tar.gz: e70e97bc700fd6d1bfc4990f0abd9925db00d8ab
+SHA512:
+  metadata.gz: 6e53264302f521efee1722d00c47f0e68f72dff220f04b7480ad2b113c35ab49cf0679ea3be430cbb95e46fb2d4076b0a68dbabc339a34d1ae0ffea22bc1cfaf
+  data.tar.gz: e55c3e48ee8508ab28c50e474fddd780f65d373c4e20b073aeebf22ab5fe2c7d4fc198299209c99b0455afe9a6c25dc240f6f9b98285f5ed1ff779b58a5e33b0

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+*.gem
+.bundle
+Gemfile.lock
+pkg
+tmp

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Douwe Maan
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,421 @@
+# Mengpaneel
+
+TL;DR: Mengpaneel makes Mixpanel a breeze to use in Rails apps by giving you a single way to interact with Mixpanel from your controllers, with Mengpaneel taking it upon itself to make sure everything gets to Mixpanel. Fast-forward to "[So… How?!](#so-how)" to get started.
+
+#### Hi
+
+Good morning, and thank you for coming. From the look on your face, I sense that you're wondering why I invited you here today.
+
+#### Sure am. Why _am_ I here?
+
+You're here because I wanted to speak with you about a little thing I built, affectionately called "Mengpaneel."
+
+#### All right, so what is "Mengpaneel?"
+
+"Mengpaneel" is the Dutch word for "mixing console."
+
+#### Sigh. What does Mengpaneel _do_?
+
+Beside the above, "Mengpaneel" is the literal Dutch translation of "[Mixpanel](https://mixpanel.com)," which you'll know as "[t]he most advanced analytics platform ever for mobile and the web."
+
+Mixpanel is great, but there are some problems you're likely to run into when trying to use it with a large server side web app.
+
+Mengpaneel aims to address these problems for Ruby on Rails, but the problems and abstract solution apply to any framework.
+
+#### You've got my attention. What "problems" are these?
+
+Let me first take a step back and explain how Mixpanel works.
+
+Put in "Explain Like I'm 5" terms, Mixpanel gathers events that happen in your app and does magic to them.
+
+Because Mixpanel doesn't know your app like you do, you're responsible for deciding what events to track, tracking these events and finally getting them to Mixpanel. To help you do this, Mixpanel provides tracking libraries for a bunch of common languages.
+
+For web apps, Mixpanel's preferred tracking library is their client side [JavaScript library](https://mixpanel.com/help/reference/javascript), going as far as actively discouraging use of libraries for [server](https://mixpanel.com/help/reference/ruby) [side](https://mixpanel.com/help/reference/python) [languages](https://mixpanel.com/help/reference/php).
+
+There's good reason for this. As they [write](https://mixpanel.com/help/reference/ruby),
+> [the JavaScript library] offers platform-specific features and conveniences that can make Mixpanel implementations much simpler, and can scale naturally to an unlimited number of clients.
+
+#### Sounds good, so let's check out this JavaScript library!
+
+All right, here's the documentation:
+
+> **Sending events**
+> 
+> Once you have the [setup] snippet in your page, you can track an event by calling `mixpanel.track` with the event name and properties.
+> 
+> ```js
+> mixpanel.track(
+>     "Clicked Ad",
+>     { "Banner Color": "Blue" }
+> );
+> ```
+
+#### That doesn't look too hard; let's go and sprinkle `mixpanel.track` calls all over our code!
+
+If only it were that easy.
+
+The example events Mixpanel uses in their library documentation ("Clicked Ad," "Played Video," etc.) have been carefully chosen to be events that exclusively happen on the client side—in the browser, where favorite child JavaScript reigns.
+
+#### Hmm. What then about server side events? Say "Place Order," clearly a database action? 
+
+Mixpanel suggests placing the `mixpanel.track` call on the page the user returns to after the event has happened, i.e. the "Thanks for your order" page. Problem solved!
+
+#### "Thank you page," you say? It's 2014, my "Sign In" action redirects wherever the user initially tried to go—I don't do "thank you" pages.
+
+And there you have our first problem.
+
+If a "Thank you!" or "Success!" page is rendered or if the user is always redirected to the same dedicated page, placing the `mixpanel.track` call there is a fine option. But if you _don't_ know where the user will be redirected to, or if you're redirecting back to something like an "index" page, you don't want to place the track call there.
+
+If you were clever, you could set a cookie `just_signed_in=true` just before redirecting, and place a check for that value in your app's layout view, but with dozens of different events, that's a slippery slope I don't want to go down.
+
+Can you think of more examples of situations where Mixpanel's assumptions don't hold so well?
+
+#### How about my "Create Blog Post" action? My `POST posts` endpoint is used by the website as well as the iPhone app—my action respects the "Accept" header, returning HTML and JSON, respectively.
+
+If your action can be used as an API returning JSON, the JavaScript tracking library isn't going to be of much use and you're gonna be missing out on events from API users.
+
+Mixpanel provides libraries for [iOS](https://mixpanel.com/help/reference/ios) and [Android](https://mixpanel.com/help/reference/android), but that doesn't help when the endpoint is used by 3rd party apps that you can hardly expect to send events to your Mixpanel account. Even if you don't allow 3rd party apps, integrating Mixpanel with your mobile app makes it hard to retroactively add events or event properties to your system, because updates to iOS and Android apps take a while to go out, which is gonna screw with your numbers until the app's been approved and every user has upgraded.
+
+And that's two problems. Can you think of one more?
+
+#### It's similar to the previous one, but what about my "Complete Payment" event? The endpoint in question is exclusively called by my payment provider to report on payment status, so it doesn't return HTML and the client isn't an app I control with its own Mixpanel library.
+
+I'm loving this conversation, you seem to know exactly where I'm going without me needing to say a word—it's almost like I'm talking to myself.
+
+Indeed, the third problem is with isolated endpoints that don't have access to any client side library to track events.
+
+#### These all seem like very common situations, are you seriously saying Mixpanel is somehow oblivious to this?
+
+I'm not. Mixpanel is definitely aware of this, which is where the aforementioned [server](https://mixpanel.com/help/reference/ruby) [side](https://mixpanel.com/help/reference/python) [libraries](https://mixpanel.com/help/reference/php) come in.
+
+As they [write](https://mixpanel.com/help/reference/ruby),
+> [t]he Mixpanel Ruby library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.
+
+Indeed, all of the problems you so pointedly pointed out can be solved by simply doing the event tracking from the server side. Instead of `mixpanel.track` calls in your views, you'll be having `mixpanel.track` calls in your controller actions.
+
+#### So what's the big deal then? Why did I have to read almost a thousand words to reach this conclusion? _Why is Mengpaneel at all?_
+
+Remember my saying the JavaScript library was Mixpanel's preferred tracking library? Remember my first quote from the Mixpanel documentation? Let me recite it again, because it's been a while:
+> [the JavaScript library] offers platform-specific features and conveniences that can make Mixpanel implementations much simpler, and can scale naturally to an unlimited number of clients.
+
+If you move away from the JavaScript library and use the Ruby library everywhere instead, you lose all of that. 
+
+One feature only readily available to the JavaScript library is the ability to link a user's previously anonymous behavior browsing your promotion website to their newly created account when they sign up. How valuable it is to know what your user did _before_ they became part of the priviliged group who decided to actually sign up cannot be overstated.
+
+Second, information about the user's device, OS and browser is very interesting, but not available to the Ruby library unless you jump through some hoops with user agent parsing on every request.
+
+Last, but definitely not least: the JavaScript library scales infinitely, while the Ruby library... doesn't. You don't want your server busy sending tens of thousands of events a day to Mixpanel, when it could be serving new (revenue generating!) requests instead.
+
+#### That makes a lot of sense. I can't believe Mixpanel hasn't properly addressed this. So how does Mengpaneel solve these problems? I'm assuming you want to sell me your magic bullet?
+
+You've got me :) 
+
+Mengpaneel addresses the problems mentioned by giving you a single way to interact with Mixpanel from your server side app, with Mengpaneel taking it upon itself to make sure everything gets to Mixpanel, using the best strategy available, whether it be client side, server side or something completely different.
+
+You can call all the "mixpanel.whatever" methods you know and love from the JavaScript library, right from your your Rails controllers, without having to worry about lack of thank you pages, unpredictable redirects, AJAX requests, endpoints with multiple response content types and clients outside your control.
+
+#### So… How?!
+
+First, install Mengpaneel by adding it to your Gemfile:
+
+```ruby
+gem "mengpaneel"
+# Don't forget to `bundle install`
+```
+
+Second, configure Mengpaneel with your Mixpanel token:
+
+```ruby
+# config/initializers/mengpaneel.rb
+
+Mengpaneel.configure do |config|
+  config.token = "abc123" # or use ENV["MIXPANEL_TOKEN"] if you're into 12-factor
+end
+```
+
+Third, include Mengpaneel in the controller(s) you plan to track Mixpanel events from. Include it in your `ApplicationController` if you want to use Mixpanel _everywhere_:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Mengpaneel::Controller
+end
+```
+
+Fourth, always identify the currently signed in user with Mixpanel:
+
+```ruby
+class ApplicationController < ActionController::Base
+  # ...
+
+  before_action :setup_mixpanel
+
+  private
+    def setup_mixpanel
+      return unless user_signed_in?
+
+      # For technical reasons, you need to do setup from a `mengpaneel.setup` block.
+      # I'll go into those reasons later.
+      mengpaneel.setup do
+        mixpanel.identify(current_user.id)
+
+        mixpanel.people.set(
+          "ID"              => current_user.id,
+          "$email"          => current_user.email,
+          "$first_name"     => current_user.first_name,
+          "$last_name"      => current_user.last_name,
+          "$created"        => current_user.created_at,
+          "$last_login"     => current_user.current_sign_in_at
+        )
+      end
+    end
+end
+```
+
+Fifth, let Mixpanel know when an anonymous user got an identity (i.e. signed up):
+
+```ruby
+class RegistrationsController < Devise::RegistrationsController
+  # Devise::RegistrationsController automatically extends ApplicationController.
+
+  def create
+    # The Devise::RegistrationsController#create action yields to its caller
+    # so you can easily extend it with custom behaviour, like we do here!
+    super do
+      # We need to make sure signing up actually succeeded.
+      if resource.errors.blank?
+        # Technical reasons again, will get into those later.
+        mengpaneel.before_setup do
+          mixpanel.alias(resource.id)
+        end
+
+        mixpanel.track("Sign Up", "ID"          => current_user.id,
+                                  "Email"       => current_user.email,
+                                  "First name"  => current_user.first_name,
+                                  "Last name"   => current_user.last_name)
+      end
+    end
+  end
+end
+```
+
+Fourth, track Mixpanel events:
+
+```ruby
+class SessionsController < Devise::SessionsController
+  def create
+    super do
+      mixpanel.track("Sign In")
+    end
+  end
+
+  def destroy
+    super do
+      mixpanel.track("Sign Out")
+    end
+  end
+end
+```
+
+```ruby
+class PostsController < ApplicationController
+  respond_to :html, :json
+
+  def create
+    @post = Post.new(post_params)
+
+    respond_with(@post) do |format|
+      if @post.save
+        mixpanel.track("Create Blog Post", "Title" => @post.title)
+
+        format.html do
+          flash[:notice] = "Successfully created blog post!"
+
+          redirect_to post_path(@post)
+        end
+
+        format.json do
+          render json: @post
+        end
+      end
+    end
+  end
+
+  private
+    def post_params
+      params.require(:post).permit(:title, :body)
+    end
+end
+```
+
+```ruby
+class PaymentNotificationsController < ApplicationController
+  before_action :authenticate!
+
+  def notify
+    if params[:status] == "payment_complete"
+      @payment = Payment.find(params[:payment_id])
+      @payment.status = :paid
+      @payment.save!
+
+      mixpanel.track("Complete Payment",  "Payment ID"  => @payment.id,
+                                          "Amount"      => @payment.amount)
+    end
+
+    response.content_type = "text/plain"
+    render text: "[accepted]"
+  end
+
+  private
+    def authenticate!
+      authenticate_or_request_with_http_basic do |username, password|
+        username == "payments" && password == "ftw"
+      end
+    end
+end
+```
+
+Finally, if you want to track events from a script or background worker instead of a controller, you can use `Mengpaneel::Manager` directly, like this:
+
+```ruby
+class SubscriptionRenewalWorker
+  include Sidekiq::Worker
+
+  def perform(subscription_id)
+    subscription = Subscription.find(subscription_id)
+
+    subscription.renew!
+
+    Mengpaneel::Manager.new do |mengpaneel|
+      mengpaneel.setup do |mixpanel|
+        mixpanel.identify(subscription.user.id)
+      end
+      
+      # Because the `mixpanel` method exposed in your controllers isn't 
+      # available here, you need to get it explicitly from Mengpaneel.
+      mengpaneel.tracking do |mixpanel|
+        mixpanel.track("Renew Subscription", "Subscription ID" => subscription.id)
+      end
+    end
+  end
+end
+```
+
+#### No, no, I mean, how does Mengpaneel do all this?
+
+This is where it gets fun. 
+
+Basically, Mengpaneel works in three stages. In describing them, it's easiest to go from back to front, so let's start with the third and final Mengpaneel stage: 
+
+###### Flush
+
+In the Flush stage, Mengpaneel makes sure events actually get to Mixpanel.
+
+As said, Mengpaneel is smart enough to decide by itself how to flush events using the best strategy available, whether it be client side, server side or something completely different.
+
+Since the problems discussed above all have to do with properties of the incoming request or outgoing response, Mengpaneel waits until you've finished building the response and then chooses a strategy by looking at the request and response.
+
+In order, these are the strategies considered:
+
+-   `Delayed`: If the response is going to be a redirect, we can't use the JavaScript library to flush events. We could immediately give up and use the Ruby library, but most of the time redirects are inbound so we'll get to a non-redirect page of our app eventually. 
+
+    Thus, we delay flushing events for now, saving them in a session to be considered in the next request.
+
+-   `ClientSide`: If the response isn't a redirect, using the JavaScript library is our best option for reasons mentioned earlier. We just need to verify that we're actually in an environment where JavaScript will be executed. That is, the response content type is HTML, we're not being requested using AJAX, we're not being downloaded as an attachment and we're not streaming data.
+
+    If all of these requirements are met, we flush all events by injecting calls to the JavaScript library into the response body.
+
+-   `CapableClientSide`: If injecting the JavaScript calls isn't going to work, our only option is to use the server side Ruby library, right? Well, not quite. Even if we can't get our code to be executed on the client side directly, we _can_ work something out with the client that's calling us, if they're willing and capable.
+
+    In this case, "capable" means that the client calling us is itself in a position to flush events to Mixpanel, and that if the server (that's us) were to give them a list of events they'd like to end up at Mixpanel, they would simply pass them along. "Willing" means they're actually advertising that capability, to be picked up on by the server.
+
+    To advertise this capability, the client adds the `X-Mengpaneel-Flush-Capable` header with value `true` to their request headers. Mengpaneel running on the server will pick up on this, and flush all tracking calls by putting them in a JSON-serialized array in the `X-Mengpaneel-Calls` response header.
+
+    When the client receives this response, it's their responsiblility to actually flush those calls to Mixpanel, by deserializing the header's contents, iterating over the events and calling the appropriate methods on the client side Mixpanel library.
+
+    This is a very useful feature in web apps with a very AJAX-heavy front end or in mobile apps, where most events would otherwise have to be flushed using the server side library but can now be flushed on the client side.
+
+    Mengpaneel comes with a small JavaScript library that does exactly what's described above for jQuery-based web apps. Install it by adding the following code to your app's main JavaScript file, after jQuery:
+
+    ```js
+    //= require jquery
+    //= require mengpaneel
+    ```
+
+    A library accomplishing the same thing should be trivial to write for iOS or Android.
+
+-   `AsyncServerSide`: And now we've arrived at our final option: using the server side Ruby library. Flush the events to Mixpanel from the same thread where the request is being handled would cause a small slowdown, so we've got one last trick up our sleeve.
+
+    If you have [Sidekiq](http://sidekiq.org/) installed, we'll queue a worker that will flush the events, to be handled by Sidekiq at a later time.
+
+    This asynchronous worker simply delegates to the last available strategy, which is also the one that will be used directly if Sidekiq isn't available, namely:
+
+-   `ServerSide`: And now we're at the _actual_ final option. If none of the other strategies where available, we use the official [`mixpanel-ruby`](https://github.com/mixpanel/mixpanel-ruby) gem to flush the events to Mixpanel right from our server side process.
+
+    At this point, some translation takes place from the JavaScript library API to the Ruby library API, to ensure you can write your controller calls as you would using the JavaScript library, while still doing The Right Thing<sup>TM</sup>.
+
+And that's end of Flush, by far the most exciting stage in Mengpaneel. More important in the grand scheme of things however, is:
+
+###### Tracking
+
+In the Tracking stage, Mengpaneel doesn't actually do all that much. This stage is filled in by your own controller; it's where you call Mixpanel methods like `alias`, `identify`, `people.set` and `track`.
+
+Mengpaneel's main responsibility is keeping track of all of the Mixpanel calls you make. Since we don't send them to Mixpanel immediately, but wait to do so until the Flush stage, we use a so-called `CallProxy` to pick up all calls so we can store them and handle them later.
+
+For technical reasons, Mengpaneel does interfere a little in this stage; you've already seen the `mengpaneel.setup` and `mengpaneel.before_setup` calls.
+
+Because Mengpaneel can delay calls until the next request, we need to make sure calls like `mixpanel.identify` and `mixpanel.people.set` aren't repeated when the next request's `mixpanel_setup` before-action is fired, because this would cause unnecessary requests to be sent to Mixpanel and would cause a flood of these when we're dealing with a chain of multiple redirects, each adding calls onto the one before it.
+
+We also need to make sure `mixpanel.alias` calls are always flushed _before_ `mixpanel.identify` calls, since they need access to the original anonymous distinct user ID.
+
+For this reason, Mengpaneel knows three modes, aptly named `before_setup`, `setup` and `tracking`—the default. To temporarily switch to a mode, simply wrap your event-tracking calls in a `mengpaneel.before_setup` or `mengpaneel.setup` block, as shown in the examples I gave before.
+
+In Flush, calls from these three modes are always called in this order, so `mixpanel.alias` comes before `mixpanel.identify` comes before `mixpanel.track`.
+
+Additionally, `mengpaneel.setup` overwrites `mengpaneel.setup` calls made earlier, thus preventing the flood of `mixpanel.identify` and `mixpanel.people.set` calls that would happen with delayed calls after a redirect.
+
+Lastly, explicitly identifying calls as "setup" or "tracking" allows us to optimize the `[Async]ServerSide` strategy by doing nothing if no actual tracking calls were made. If we're not sending events, there's no need to do setup at all.
+
+With tracking finished, we've arrived at the first stage to be executed and the last stage to be discussed, called:
+
+###### Replay
+
+In the Replay stage, Mengpaneel replays previously delayed calls.
+
+As mentioned under Flush, the `Delayed` strategy delays flushing calls until the next request if the current one is a redirect by saving them in a session.
+
+Before your controller action is called, Replayer does nothing more than reading this session, iterating over the calls saved therein and calling them in their respective tracking modes, just like you did from inside your controller action in the previous request, thus making sure no delayed calls get lost.
+
+And there you have it!
+
+#### Dude. Who are you, I mean, who should I thank for this?
+
+My name is [Douwe Maan](http://www.douwemaan.com) and I'm a co-founder-slash-developer at [Stinngo](http://www.stinngo.com).
+
+Besides that, you should thank [Mixpanel](https://mixpanel.com) since without them this project would've been very pointless indeed, as well as gems [event_tracker](https://github.com/doorkeeper/event_tracker) and [analytical](https://github.com/jkrall/analytical) from which I've taken inspiration.
+
+#### Cool. And I can just, like, use this in my apps?
+
+Sure, as long as you adhere to the following license:
+
+> Copyright (c) 2014 Douwe Maan
+> 
+> MIT License
+> 
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+> 
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/app/assets/javascripts/mengpaneel.js

@@ -0,0 +1,48 @@
+(function($, undefined) {
+  var REQUEST_HEADER  = "X-Mengpaneel-Flush-Capable";
+  var RESPONSE_HEADER = "X-Mengpaneel-Calls";
+
+  if (!window.mixpanel) return;
+
+  $(document).on("ajaxSend", function(event, xhr, options) {
+    if (options.crossDomain) return;
+
+    xhr.setRequestHeader(REQUEST_HEADER, "true");
+  });
+
+  $(document).on("ajaxComplete", function(event, xhr, options) {
+    if (options.crossDomain) return;
+
+    var rawCalls = xhr.getResponseHeader(RESPONSE_HEADER);
+    if (!rawCalls) return;
+
+    var calls;
+    try { 
+      calls = $.parseJSON(rawCalls);
+    }
+    catch (e) {
+      return;
+    }
+
+    for(var i = 0, length = calls.length; i < length; i++) {
+      var call = calls[i];
+      var methodNames = call[0];
+      var args = call[1];
+
+      var object = window.mixpanel;
+      if (!object) return;
+
+      var methodName = methodNames.pop();
+
+      for(var j = 0, length2 = methodNames.length; j < length2; j++) {
+        var name = methodNames[j];
+
+        object = object[name];
+      }
+
+      var method = object[methodName];
+
+      method.apply(object, args);
+    }
+  });
+})(jQuery);

data/lib/mengpaneel/call_proxy.rb

@@ -0,0 +1,51 @@
+module Mengpaneel
+  class CallProxy
+    attr_reader :method_name
+    attr_reader :args
+    attr_reader :calls
+
+    def initialize(method_name = nil, args = [])
+      @method_name  = method_name
+      @args         = args
+
+      @calls = []
+    end
+
+    def method_missing(method_name, *args)
+      save_call(method_name, *args)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      true
+    end
+
+    def full_method_name(prefixes)
+      [*prefixes, *self.method_name]
+    end
+
+    def to_call(prefixes = [])
+      [full_method_name(prefixes), args] if self.method_name
+    end
+
+    def child_calls(prefixes = [])
+      method_name = full_method_name(prefixes)
+      @calls.flat_map { |proxy| proxy.all_calls(method_name) }
+    end
+
+    def all_calls(prefixes = [])
+      calls = []
+      calls << to_call(prefixes) if self.method_name && (@calls.empty? || !@args.empty?)
+      calls += child_calls(prefixes)
+      calls
+    end
+
+    private
+      def save_call(method_name, *args)
+        proxy = self.class.new(method_name, args)
+
+        @calls << proxy
+
+        proxy
+      end
+  end
+end

data/lib/mengpaneel/controller.rb

@@ -0,0 +1,28 @@
+require "active_support/concern"
+
+require "mengpaneel/manager"
+
+module Mengpaneel
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      prepend_around_action :wrap_in_mengpaneel
+
+      delegate :mixpanel, to: :mengpaneel
+
+      helper_method :mengpaneel, :mixpanel
+    end
+
+    def mengpaneel
+      @mengpaneel ||= Manager.new(self)
+    end
+
+    private
+      def wrap_in_mengpaneel(&block)
+        mengpaneel.wrap do
+          yield
+        end
+      end
+  end
+end

data/lib/mengpaneel/delayer.rb

@@ -0,0 +1,25 @@
+module Mengpaneel
+  class Delayer
+    SESSION_KEY = "mengpaneel_delayed_calls".freeze
+
+    attr_reader :controller
+
+    def initialize(controller = nil)
+      @controller = controller
+    end
+
+    def load
+      (controller.session[SESSION_KEY] || {}).with_indifferent_access
+    end
+
+    def load!
+      calls = load
+      controller.session.delete(SESSION_KEY)
+      calls
+    end
+
+    def save(all_calls)
+      controller.session[SESSION_KEY] = all_calls
+    end
+  end
+end

data/lib/mengpaneel/engine.rb

@@ -0,0 +1,4 @@
+module Mengpaneel
+  class Engine < Rails::Engine
+  end
+end

data/lib/mengpaneel/flusher.rb

@@ -0,0 +1,39 @@
+require "mengpaneel/strategy/delayed"
+require "mengpaneel/strategy/client_side"
+require "mengpaneel/strategy/capable_client_side"
+require "mengpaneel/strategy/async_server_side"
+require "mengpaneel/strategy/server_side"
+
+module Mengpaneel
+  class Flusher
+    STRATEGIES = [
+      Strategy::Delayed,
+      Strategy::ClientSide,
+      Strategy::CapableClientSide,
+      Strategy::AsyncServerSide,
+      Strategy::ServerSide
+    ]
+
+    attr_reader :manager
+
+    def initialize(manager)
+      @manager = manager
+    end
+
+    def run
+      return unless Mengpaneel.token
+      
+      if manager.flushing_strategy
+        strategy = Strategy.const_get(manager.flushing_strategy.to_s.classify)
+        flush_using(strategy)
+      else
+        STRATEGIES.find { |strategy| flush_using(strategy) }
+      end
+    end
+
+    private
+      def flush_using(strategy)
+        strategy.new(manager.all_calls, manager.controller).run
+      end
+  end
+end

data/lib/mengpaneel/manager.rb

@@ -0,0 +1,92 @@
+require "mengpaneel/call_proxy"
+require "mengpaneel/replayer"
+require "mengpaneel/flusher"
+
+module Mengpaneel
+  class Manager
+    MODES = %i(before_setup setup tracking).freeze
+
+    attr_reader   :controller
+    attr_reader   :mode
+
+    attr_accessor :flushing_strategy
+
+    def initialize(controller = nil, &block)
+      @controller = controller
+
+      @mode = :tracking
+
+      wrap(&block) if block
+    end
+
+    def wrap(&block)
+      replay_delayed_calls
+      
+      if block.arity == 1
+        yield(self)
+      else
+        yield
+      end
+    ensure
+      flush_calls
+    end
+
+    def call_proxy
+      call_proxies[@mode]
+    end
+    alias_method :mixpanel, :call_proxy
+
+    def clear_calls(mode = @mode)
+      call_proxies.delete(mode)
+    end
+
+    def all_calls
+      call_proxies.map { |mode, call_proxy| [mode, call_proxy.all_calls] }.to_h
+    end
+
+    def with_mode(mode, &block)
+      original_mode = @mode
+      @mode = mode
+
+      begin
+        if block.arity == 1
+          yield(mixpanel)
+        else
+          yield
+        end
+      ensure
+        @mode = original_mode
+      end
+    end
+
+    def before_setup(&block)
+      with_mode(:before_setup, &block)
+    end
+
+    def setup(&block)
+      clear_calls(:setup)
+      with_mode(:setup, &block)
+    end
+
+    def tracking(&block)
+      with_mode(:tracking, &block)
+    end
+
+    def setup?
+      call_proxies[:setup].all_calls.length > 0
+    end
+
+    def replay_delayed_calls
+      Replayer.new(self).run
+    end
+
+    def flush_calls
+      Flusher.new(self).run
+    end
+
+    private
+      def call_proxies
+        @call_proxies ||= Hash.new { |proxies, mode| proxies[mode] = CallProxy.new }
+      end
+  end
+end

data/lib/mengpaneel/replayer.rb

@@ -0,0 +1,40 @@
+require "mengpaneel/delayer"
+
+module Mengpaneel
+  class Replayer
+    attr_reader :manager
+
+    def initialize(manager)
+      @manager = manager
+    end
+
+    def run
+      return unless manager.controller
+      
+      delayed_calls = Delayer.new(manager.controller).load!
+
+      Manager::MODES.each do |mode|
+        next unless delayed_calls.has_key?(mode)
+
+        calls = delayed_calls[mode] || []
+
+        manager.send(mode) do
+          replay_calls(calls)
+        end
+      end
+    end
+
+    private
+      def replay_calls(calls)
+        proxy = manager.call_proxy
+
+        calls.each do |method_names, args|
+          method_name = method_names.pop
+
+          object = method_names.inject(proxy) { |object, method_name| object.public_send(method_name) }
+          
+          object.public_send(method_name, *args)
+        end
+      end
+  end
+end

data/lib/mengpaneel/strategy/async_server_side.rb

@@ -0,0 +1,35 @@
+require "mengpaneel/strategy/base"
+require "mengpaneel/strategy/server_side"
+
+module Mengpaneel
+  module Strategy
+    class AsyncServerSide < Base
+      def run
+        return false unless self.class.async?
+
+        return true if all_calls[:tracking].blank?
+
+        Worker.perform_async(all_calls, controller.try(:request).try(:remote_ip))
+
+        true
+      end
+
+      private
+        def self.async?
+          defined?(::Sidekiq)
+        end
+
+      if async?
+        class Worker
+          include Sidekiq::Worker
+
+          def perform(all_calls, remote_ip = nil)
+            all_calls = all_calls.with_indifferent_access
+            
+            Strategy::ServerSide.new(all_calls, nil, remote_ip).run
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mengpaneel/strategy/base.rb

@@ -0,0 +1,17 @@
+module Mengpaneel
+  module Strategy
+    class Base
+      attr_reader :all_calls
+      attr_reader :controller
+
+      def initialize(all_calls, controller = nil)
+        @all_calls  = all_calls
+        @controller = controller
+      end
+
+      def run
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/mengpaneel/strategy/capable_client_side.rb

@@ -0,0 +1,28 @@
+require "mengpaneel/strategy/base"
+
+module Mengpaneel
+  module Strategy
+    class CapableClientSide < Base
+      REQUEST_HEADER  = "X-Mengpaneel-Flush-Capable".freeze
+      RESPONSE_HEADER = "X-Mengpaneel-Calls".freeze
+
+      delegate :request, :response, to: :controller, allow_nil: true
+
+      def run
+        return false unless controller
+        return false unless capable?
+
+        return true if all_calls[:tracking].blank?
+
+        response.headers[RESPONSE_HEADER] = JSON.dump(all_calls[:tracking])
+
+        true
+      end
+
+      private
+        def capable?
+          %w(true 1).include?(request.headers[REQUEST_HEADER])
+        end
+    end
+  end
+end

data/lib/mengpaneel/strategy/client_side.rb

@@ -0,0 +1,92 @@
+require "mengpaneel/strategy/base"
+
+module Mengpaneel
+  module Strategy
+    class ClientSide < Base
+      SETUP_CODE = <<-CODE.strip_heredoc
+        (function(f,b){if(!b.__SV){var a,e,i,g;window.mixpanel=b;b._i=[];b.init=function(a,e,d){function f(b,h){var a=h.split(".");2==a.length&&(b=b[a[0]],h=a[1]);b[h]=function(){b.push([h].concat(Array.prototype.slice.call(arguments,0)))}}var c=b;"undefined"!==typeof d?c=b[d]=[]:d="mixpanel";c.people=c.people||[];c.toString=function(b){var a="mixpanel";"mixpanel"!==d&&(a+="."+d);b||(a+=" (stub)");return a};c.people.toString=function(){return c.toString(1)+".people (stub)"};i="disable track track_pageview track_links track_forms register register_once alias unregister identify name_tag set_config people.set people.set_once people.increment people.append people.track_charge people.clear_charges people.delete_user".split(" ");
+        for(g=0;g<i.length;g++)f(c,i[g]);b._i.push([a,e,d])};b.__SV=1.2;a=f.createElement("script");a.type="text/javascript";a.async=!0;a.src="//cdn.mxpnl.com/libs/mixpanel-2.2.min.js";e=f.getElementsByTagName("script")[0];e.parentNode.insertBefore(a,e)}})(document,window.mixpanel||[]);
+      CODE
+
+      delegate :request, :response, :env, to: :controller, allow_nil: true
+
+      def run
+        return false unless controller
+        return false unless client_side?
+
+        response_body = response.body
+
+        head_end = response_body.index("</head")
+        return false unless head_end
+
+        if source = source_for_head
+          response_body.insert(head_end, source)
+        end
+
+        body_end = response_body.index("</body")
+        return false unless body_end
+
+        if source = source_for_body
+          response_body.insert(body_end, source)
+        end
+
+        response.body = response_body
+
+        true
+      end
+
+      private
+        def source_for_head
+          [
+            %{<script type="text/javascript">},
+              SETUP_CODE,
+
+              %{mixpanel.init(#{Mengpaneel.token.to_json});},
+              
+              *javascript_calls(:before_setup),
+              *javascript_calls(:setup),
+            %{</script>}
+          ].join("\n")
+        end
+
+        def source_for_body
+          return if all_calls[:tracking].blank?
+
+          [
+            %{<script type="text/javascript">},
+              *javascript_calls(:tracking),
+            %{</script>}
+          ].join("\n")
+        end
+
+        def javascript_calls(mode)
+          calls = all_calls[mode] || []
+
+          calls.map do |method_names, args|
+            method_name = method_names.join(".")
+            arguments   = args.map(&:to_json).join(", ")
+
+            %{mixpanel.#{method_name}(#{arguments});}
+          end
+        end
+
+        def client_side?
+          html? && !request.xhr? && !attachment? && !streaming?
+        end
+
+        def html?
+          response.content_type && response.content_type.include?("text/html")
+        end
+
+        def attachment?
+          response.headers["Content-Disposition"].to_s.include?("attachment")
+        end
+
+        def streaming?
+          return false unless defined?(ActionController::Live)
+
+          env["action_controller.instance"].class.included_modules.include?(ActionController::Live)
+        end
+    end
+  end
+end

data/lib/mengpaneel/strategy/delayed.rb

@@ -0,0 +1,22 @@
+require "mengpaneel/strategy/base"
+require "mengpaneel/delayer"
+
+module Mengpaneel
+  module Strategy
+    class Delayed < Base
+      def run
+        return false unless controller
+        return false unless redirect?
+
+        Delayer.new(controller).save(all_calls)
+
+        true
+      end
+
+      private
+        def redirect?
+          (300...400).include?(controller.response.status)
+        end
+    end
+  end
+end

data/lib/mengpaneel/strategy/server_side.rb

@@ -0,0 +1,41 @@
+require "mengpaneel/strategy/base"
+require "mengpaneel/tracker"
+
+module Mengpaneel
+  module Strategy
+    class ServerSide < Base
+      def initialize(all_calls, controller = nil, remote_ip = nil)
+        super(all_calls, controller)
+
+        @remote_ip = remote_ip || controller.try(:request).try(:remote_ip)
+      end
+
+      def run
+        return true if all_calls[:tracking].blank?
+
+        perform_calls(:before_setup)
+        perform_calls(:setup)
+        perform_calls(:tracking)
+
+        true
+      end
+
+      private
+        def tracker
+          @tracker ||= Tracker.new(Mengpaneel.token, @remote_ip)
+        end
+
+        def perform_calls(mode)
+          calls = all_calls[mode] || []
+
+          calls.each do |method_names, args|
+            method_name = method_names.pop
+
+            object = method_names.inject(tracker) { |object, method_name| object.public_send(method_name) }
+
+            object.public_send(method_name, *args)
+          end
+        end
+    end
+  end
+end

data/lib/mengpaneel/tracker.rb

@@ -0,0 +1,95 @@
+require "active_support/hash_with_indifferent_access"
+require "mixpanel-ruby"
+
+module Mengpaneel
+  class Tracker < Mixpanel::Tracker
+    attr_reader :token
+    attr_reader :remote_ip
+    attr_reader :distinct_id
+
+    def initialize(token, remote_ip = nil)
+      super(token)
+      @people = People.new(self)
+
+      @remote_ip = remote_ip
+
+      @disable_all_events = false
+      @disabled_events = []
+
+      @properties = HashWithIndifferentAccess.new
+      @properties["ip"] = @remote_ip if @remote_ip
+    end
+
+    def push(item)
+      method_name, args = item
+      send(method_name, *args)
+    end
+
+    def disable(events = nil)
+      if events
+        @disabled_events += events
+      else
+        @disable_all_events = true
+      end
+    end
+
+    def identify(distinct_id)
+      @distinct_id = distinct_id
+    end
+
+    def register(properties)
+      @properties.merge!(properties)
+    end
+
+    def register_once(properties, default_value = "None")
+      @properties.merge!(properties) do |key, oldval, newval|
+        oldval.nil? || oldval == default_value ? newval : oldval
+      end
+    end
+
+    def unregister(property)
+      @properties.delete(property)
+    end
+
+    def get_property(property)
+      @properties[property]
+    end
+
+    def track(event, properties = {})
+      return if @disable_all_events || @disabled_events.include?(event)
+
+      properties = @properties.merge(properties)
+
+      super(@distinct_id, event, properties)
+    end
+
+    %i(track_links track_forms alias set_config get_config).each do |name|
+      define_method(name) do |*args|
+        # Not supported on server side
+      end
+    end
+
+    class People < Mixpanel::People
+      attr_reader :tracker
+
+      def initialize(tracker)
+        @tracker = tracker
+        
+        super(tracker.token)
+      end
+
+      %i(set set_once increment append track_charge clear_charges delete_user).each do |method_name|
+        define_method(method_name) do |*args|
+          args.unshift(tracker.distinct_id) unless args.first == tracker.distinct_id
+          super(*args)
+        end
+      end
+
+      def update(message)
+        message["$ip"] = tracker.remote_ip
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/mengpaneel/version.rb

@@ -0,0 +1,3 @@
+module Mengpaneel
+  VERSION = "0.0.1"
+end

data/lib/mengpaneel.rb

@@ -0,0 +1,11 @@
+require "mengpaneel/version"
+require "mengpaneel/engine"
+require "mengpaneel/controller"
+
+module Mengpaneel
+  mattr_accessor :token
+  
+  def self.configure(&block)
+    yield(self)
+  end
+end

data/mengpaneel.gemspec

@@ -0,0 +1,21 @@
+$:.unshift File.expand_path("../lib", __FILE__)
+require "mengpaneel/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "mengpaneel"
+  spec.version       = Mengpaneel::VERSION
+  spec.author        = "Douwe Maan"
+  spec.email         = "douwe@selenight.nl"
+  spec.summary       = "Mengpaneel makes Mixpanel a breeze to use in Rails apps."
+  spec.description   = "Mengpaneel gives you a single way to interact with Mixpanel from your Rails controllers, with Mengpaneel taking it upon itself to make sure everything gets to Mixpanel."
+  spec.homepage      = "https://github.com/DouweM/mengpaneel"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency "activesupport"
+  spec.add_dependency "mixpanel-ruby"
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: mengpaneel
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Douwe Maan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mixpanel-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Mengpaneel gives you a single way to interact with Mixpanel from your
+  Rails controllers, with Mengpaneel taking it upon itself to make sure everything
+  gets to Mixpanel.
+email: douwe@selenight.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/mengpaneel.js
+- lib/mengpaneel.rb
+- lib/mengpaneel/call_proxy.rb
+- lib/mengpaneel/controller.rb
+- lib/mengpaneel/delayer.rb
+- lib/mengpaneel/engine.rb
+- lib/mengpaneel/flusher.rb
+- lib/mengpaneel/manager.rb
+- lib/mengpaneel/replayer.rb
+- lib/mengpaneel/strategy/async_server_side.rb
+- lib/mengpaneel/strategy/base.rb
+- lib/mengpaneel/strategy/capable_client_side.rb
+- lib/mengpaneel/strategy/client_side.rb
+- lib/mengpaneel/strategy/delayed.rb
+- lib/mengpaneel/strategy/server_side.rb
+- lib/mengpaneel/tracker.rb
+- lib/mengpaneel/version.rb
+- mengpaneel.gemspec
+homepage: https://github.com/DouweM/mengpaneel
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Mengpaneel makes Mixpanel a breeze to use in Rails apps.
+test_files: []