<commit_before>== What is Mixpanel (the service) ?

Mixpanel is a real-time analytics service that helps companies understand how users interact with web applications.
http://mixpanel.com

== What does this Gem do?

* Track events with properties directly from your backend.
* Track events with properties through javascript using a rack middleware.


== How to install?

  gem install mixpanel


== How to use it with a Rails application?

Add this to your environment config file or create a new initializer for it...

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN"

By default the scripts are inserted into the head of the html response. If you'd prefer the scripts to run after all rendering has completed you can set the insert_js_last flag and they'll be added at the end of the body tag. This will work whether or not you opt for the aynchronous version of the API. However, when inserting js into an ajax response it will have no effect:

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", :insert_js_last => true

You can also pass Mixpanel configuration details as seen here (https://mixpanel.com/docs/integration-libraries/javascript-full-api#set_config):

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", :config => {:debug => true}
  
In your application_controller class add a method to instance mixpanel.

  before_filter :initialize_mixpanel

  def initialize_mixpanel
    @mixpanel = Mixpanel::Tracker.new("YOUR_MIXPANEL_API_TOKEN", request.env, true)
  end

Then in each request you want to track some event you can use:

To track events directly from your backend...

  @mixpanel.track_event("Sign in", {:some => "property"})

To track events after response with javascript...

  @mixpanel.append_event("Sign in", {:some => "property"})

To execute any javascript API call

  @mixpanel.append_api("register", {:some => "property"})
  @mixpanel.append_api("identify", "Unique Identifier")

If you are proxying Mixpanel API requests then you can set a custom url and additionally stop the token from being sent by marking it as false if you're going to let the proxy add it...

  @mixpanel = Mixpanel::Tracker.new(false, request.env, true, 'http://localhost:8000/mixpanelproxy?data=')

== Resque and Rails example

If you don't want to use the built in Mixpanel Gem async feature bellow there is an example about how to make async calls using Resque.

{Resque is a Redis-backed Ruby library for creating background jobs}[https://github.com/defunkt/resque]

    class MixpanelTrackEventJob
      @queue = :slow

      def mixpanel(request_env)
        Mixpanel.new(MIXPANEL_TOKEN, request_env)
      end

      def perform(name, params, request_env)
        mixpanel(request_env).track_event(name, params)
      end
    end

    class UsersController < ApplicationController
      def create
        @user = User.new(params[:user])

        if @user.save
          MixpanelTrackEventJob.enqueue("Sign up", {:invited => params[:invited]}, request.env)
          redirect_to user_root_path
        else
          render :new
        end
     end
   end
<commit_msg>Updated documentation for persistence layer<commit_after>== What is Mixpanel (the service) ?

Mixpanel is a real-time analytics service that helps companies understand how users interact with web applications.
http://mixpanel.com

== What does this Gem do?

* Track events with properties directly from your backend.
* Track events with properties through javascript using a rack middleware.


== How to install?

  gem install mixpanel


== How to use it with a Rails application?

Add this to your environment config file or create a new initializer for it...

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN"

By default the scripts are inserted into the head of the html response. If you'd prefer the scripts to run after all rendering has completed you can set the insert_js_last flag and they'll be added at the end of the body tag. This will work whether or not you opt for the aynchronous version of the API. However, when inserting js into an ajax response it will have no effect:

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", :insert_js_last => true

You can also pass Mixpanel configuration details as seen here (https://mixpanel.com/docs/integration-libraries/javascript-full-api#set_config):

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", :config => {:debug => true}
  
In your application_controller class add a method to instance mixpanel.

  before_filter :initialize_mixpanel

  def initialize_mixpanel
    @mixpanel = Mixpanel::Tracker.new("YOUR_MIXPANEL_API_TOKEN", request.env, true)
  end

Then in each request you want to track some event you can use:

To track events directly from your backend...

  @mixpanel.track_event("Sign in", {:some => "property"})

To track events after response with javascript...

  @mixpanel.append_event("Sign in", {:some => "property"})

To execute any javascript API call

  @mixpanel.append_api("register", {:some => "property"})
  @mixpanel.append_api("identify", "Unique Identifier")

If you are proxying Mixpanel API requests then you can set a custom url and additionally stop the token from being sent by marking it as false if you're going to let the proxy add it...

  @mixpanel = Mixpanel::Tracker.new(false, request.env, true, 'http://localhost:8000/mixpanelproxy?data=')

== Resque and Rails example

If you don't want to use the built in Mixpanel Gem async feature bellow there is an example about how to make async calls using Resque.

{Resque is a Redis-backed Ruby library for creating background jobs}[https://github.com/defunkt/resque]

    class MixpanelTrackEventJob
      @queue = :slow

      def mixpanel(request_env)
        Mixpanel.new(MIXPANEL_TOKEN, request_env)
      end

      def perform(name, params, request_env)
        mixpanel(request_env).track_event(name, params)
      end
    end

    class UsersController < ApplicationController
      def create
        @user = User.new(params[:user])

        if @user.save
          MixpanelTrackEventJob.enqueue("Sign up", {:invited => params[:invited]}, request.env)
          redirect_to user_root_path
        else
          render :new
        end
     end
   end

== Persistence

If you would like, the Mixpanel gem may be configured to store its queue in a Rack session. This allows events to be stored through redirects, helpful if you sign in and redirect but want to associate an event with that action.

The mixpanel gem will also remove duplicate events from your queue for information that should only be trasmitted to the API once, such as `mixpanel.identify`, `mixpanel.name_tag`, `mixpanel.people.set`, and `mixpanel.register`. This allows you to use a before filter to set these variables, redirect, and still have them only transmitted once.

To enable persistence, you must set it in two places. Once when you initialize the middleware...

    config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", persistence: true

And once when you initialize a tracker:

    before_filter :initialize_mixpanel

    def initialize_mixpanel
      @mixpanel = Mixpanel::Tracker.new("YOUR_MIXPANEL_API_TOKEN", request.env, true, true)
    end

{'fraction_non_alphanumeric': 0.07702702702702703, 'fraction_numerical': 0.001081081081081081, 'mean_word_length': 4.097107438016529, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 17, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '165964', 'n_tokens_mistral': 2095, 'n_tokens_neox': 1988, 'n_words': 844}