aarrr 0.0.1

data/Gemfile

@@ -0,0 +1,16 @@
+source :rubygems
+
+gemspec
+
+gem "bson_ext"
+
+gem "ruby-debug", :platforms => :mri_18
+gem "ruby-debug19", :platforms => :mri_19
+
+gem "rb-fsevent"
+gem "growl"
+
+gem "guard"
+gem "guard-rspec"
+
+gem "rake", "= 0.8.7"

data/Gemfile.lock

@@ -0,0 +1,67 @@
+PATH
+  remote: .
+  specs:
+    aarrr (0.0.1)
+      mongo (>= 1.3.1)
+      rack (>= 1.2.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    bson (1.3.1)
+    bson_ext (1.3.1)
+    columnize (0.3.2)
+    diff-lcs (1.1.2)
+    growl (1.0.3)
+    guard (0.3.4)
+      thor (~> 0.14.6)
+    guard-rspec (0.3.1)
+      guard (>= 0.2.2)
+    linecache (0.43)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    mongo (1.3.1)
+      bson (>= 1.3.1)
+    rack (1.3.0)
+    rake (0.8.7)
+    rb-fsevent (0.4.0)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.3)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    thor (0.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  aarrr!
+  bson_ext
+  growl
+  guard
+  guard-rspec
+  rake (= 0.8.7)
+  rb-fsevent
+  rspec (>= 2.0)
+  ruby-debug
+  ruby-debug19

data/Guardfile

@@ -0,0 +1,6 @@
+guard 'rspec' do
+  watch('spec/spec_helper.rb')                       { "spec" }
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^lib/(.+)\.rb})                           { "spec" } # { |m| "spec/lib/#{m[1]}_spec.rb" }
+end
+

data/LICENSE

@@ -0,0 +1,69 @@
+Copyright (c) 2011 Jacques Crocker
+
+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.
+
+
+Parts taken from Mongoid library:
+
+Copyright (c) 2009 Durran Jordan
+
+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.
+
+
+
+Parts taken from Vanity library:
+
+Copyright (c) 2010 Assaf Arkin
+
+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,286 @@
+AARRR - metrics for Pirates
+-----------------------------
+
+AARRR is a MongoDB backed ruby library that helps you track **user lifecycle** metrics for your web apps (with cohorts!).
+
+The name comes from an acronym coined by Dave McClure that represents the five most important early metrics for any web startup: Acquisition, Activation, Revenue, Retention, and Referral.
+
+A quick 5 min video:<br>
+<http://500hats.typepad.com/500blogs/2007/09/startup-metrics.html>
+
+Learn more about startup metrics for Pirates:<br>
+<http://www.slideshare.net/dmc500hats/startup-metrics-for-pirates-long-version>
+
+![mascot](https://github.com/railsjedi/aarrr/raw/master/aarrr.png "Mascot")
+
+## Why you should use AARRR:
+
+AARRR is meant to quickly get you started and provide a framework for collecting and displaying data. It's goal is to help you learn what to measure, and quickly get results. It's long term goal is to really get you to think very hard about how to measure and track your users in order to provide actionable metrics about your web app.
+
+While it has support for split testing, it's main goal is to provide macro metrics for your users. For more micro experiment driven metrics, you should check out tools such as [Vanity](https://github.com/assaf/vanity) and [ABingo](http://www.bingocardcreator.com/abingo)
+
+
+## Features:
+
+* Easily define custom [cohorts](http://www.avc.com/a_vc/2009/10/the-cohort-analysis.html) (defaults to weekly cohorts). You can also define cohorts for specific deploys, or by traffic source.
+
+* Uses MongoDB for storing analytics (no schema needed, and super crazy fast writes)
+
+* Automatic configuration for Mongoid and MongoMapper users
+
+* Easily hooks into Devise (to capture User Acquisition event)
+
+
+## How to Install:
+
+* Add `gem "aarrr"` to your Gemfile and `bundle`
+
+* Run `rails g aarrr:install` to generate your initializer
+
+* If you'd like to customize the MongoDB connection (or if you aren't using Mongoid/MongoMapper, then edit `config/initializers/aarrr.rb` and set `AARRR.connection` to a valid `Mongo::Connection`. See the [mongo gem tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html) for quick an easy instructions on how to set up a `Mongo::Connection`
+
+AARRR is now set up, and will add an `around` filter to each request so it can handle user tracking. When a user first shows up at your site, we'll add in a "_utmarr" permanent cookie to them that uniquely identifies the user. You can configure this cookie in `config/initializers/aarrr.rb`.
+
+
+## How to add tracking
+
+AARRR defines a helper method `AARRR()` that returns a "session" object.  actually just an alias to AARRR::Session.new(). The session object's purpose is to define a user uniquely. All tracking events should be called from the session object
+
+You can get a session in a few different ways:
+
+    # from an env hash (we'll pull out the right cookie tracking code)
+    AARRR(request.env)
+
+    # directly from a user (if they're already logged in)
+    # use this if you are doing tracking from model objects (you just need a reference to the user)
+    AARRR(current_user)
+
+    # pass in the tracking code directly
+    AARRR(cookies["_utmarrr"])
+
+You should then save the session to cookie: `AARRR(request.env).save(response)`
+
+### Tracking vs Completion events
+
+For each category of events, you can track multiple events leading up to the actual "completion" step for a category, use the option `:in_progress => true`
+
+
+### Acquisition
+
+You'll probably want to track customer acquisition at the time of user signup. We can automatically hook into Devise so this event is triggered as soon as your user signs up.
+
+If you'd rather define Acquisition events manually, just use:
+
+    AARRR(request.env).acquisition!(:viewed_homepage)
+
+To track the funnel leading up to the acquisition event, use:
+
+    AARRR(request.env).acquisition!(:opened_signup_popup, :in_progress => true)
+
+
+### Activation
+
+Activation events should be tracked as soon as your user interacts "sucessfully" with your app. You'll need to define this for your own app, however if your app is built to do something specific then you should add an activation event whenever that thing happens.
+
+    AARRR(request.env).activation!(:built_page)
+
+    AARRR(request.env).activation!(:finished_game)
+
+
+### Retention
+
+Retention is defined by how often your user keeps coming back to the app. You can define retention rules separately in reports (e.g. 5 times in 2 months)
+
+    AARRR(request.env).retention!(:logged_in)
+
+
+### Referral
+
+Referral should be triggered whenever someone gets someone else to sign up to your app. It's used to calculate a Virality coefficient which is. Learn more about the virality coefficient [here](http://andrewchenblog.com/2008/04/17/viral-coefficient-what-it-does-and-does-not-measure/).
+
+
+Referrals are done in 2 parts. First you can track when someone decides to refer someone. This would be an "invite" link or something similar.
+
+    # generate a referral
+    referral_code = AARRR(request.env).sent_referral!(:sent => {email: "someone@somewhere.com"})
+
+    # email out the url with this referral code in the query param
+    # "?_a=x71n5"
+
+    # after accepting the code
+    AARRR(request.env).accept_referral!(code)
+
+When someone enters the site without an activated session and a referral code shows up, then we track the referral event as soon as the user signs up.
+
+
+### Track
+
+Track allows you to trigger multiple events at a time. (defaults to :activation event)
+
+    AARRR(request.env).track!(:built_page, :event_type => :activate, :in_progress => true)
+
+
+### Revenue
+
+Whenever you capture a dollar from user, then you should track that intake event.
+
+    # customer paid you 55.00
+    AARRR(request.env).revenue!(55.00)
+
+    # can also pass in the cents
+    AARRR(request.env).revenue_cents!(5500)
+
+    # it's also useful to pass in a unique code here (receipt / invoice number or something) so you don't double track someone's revenue
+    AARRR(request.env).revenue!(55.00, :unique => "x8175m1o58113")
+
+
+## Cohorts
+
+Cohorts are ways to slice up reports so you can see the results for these 5 metrics for groups of specific users. Some useful examples are:
+
+### Date (by day, week, month)
+
+slice up the metrics based on when users first came to your site (session creation). This is useful to see if what your building is actually improving your metrics
+
+
+    # assigns a cohort based on the week
+    AARRR.define_cohort :weekly do |user|
+      user["created_at"].beginning_of_week.strftime("%B %d, %Y")
+    end
+
+
+### By Traffic Source
+
+slice up the metrics based on where your users are coming from. This allows you to see what sources of traffic are most value and target your marketing efforts on these.
+
+    # assigns a cohort based on the traffic source
+    AARRR.define_cohort :source do |user|
+      case user["referrer"]
+      when /google.com/, /gmail.com/
+        "google"
+      when /facebook.com/
+        "facebook"
+      else
+        nil
+      end
+    end
+
+### By Keyword
+
+slice up the users by the keyword (or groups of keyword) in order to classify users by market segment.
+
+    AARRR.define_cohort :keyword do |user, data|
+      # define a `extract_keywords` method to pull out the keywords from the referrer url
+      keywords = extract_keywords(user["referrer"])
+      if keywords.include?("ruby") or keywords.include?("rails")
+        "rails"
+      else
+        nil
+      end
+    end
+
+
+### By gender (or other custom data attributes)
+
+assuming you've captured it via `AARRR(request.env).set_data(:gender => "m")`
+
+    AARRR.define_cohort :gender do |user, data|
+      if data["gender"].to_s.upcase == "M"
+        "male"
+      elsif data["gender"].to_s.upcase == "F"
+        "female"
+      else
+        nil
+      end
+    end
+
+### By Location
+
+    AARRR.define_cohort :location do |user, data|
+      # define get_city_for method to get the city for a particular ip address
+      get_city_for(user["ip_address"])
+    end
+
+
+## Split Testing
+
+You can set up split testing by using:
+
+    AARRR.define_split :landing_redesign, :options => {
+      :v1_layout => 0.9,
+      :v2_layout => 0.1
+    }
+
+To use these split tests, just add the following to your views:
+
+    AARRR(request.env).split?(:landing_redesign, :v1_layout) #=> true
+
+The first argument is a reference to the split test that you defined in your initializer. The second argument is the split option to return.
+
+This will attach the session with a randomly selected version of the split test and return whether it matches the second argument.
+
+You can also just return the split option currently assigned to the user by using:
+
+    AARRR(request.env).split(:landing_redesign) #=> :v1_layout
+
+Split test results can be accessed via the reports, and you can slice up the user metrics based on which users saw what split. People who saw neither splits will not be included in the results.
+
+
+## Ignored Cohorts
+
+When you start seeing screwy data (spammers, seo, scrapers) you can selectively remove these people by configuring Ignored Cohorts. This just excludes data before running the report calculations.
+
+This allows you to identify the AARRR users that are likely "spam" and removes them from most report results.
+
+    # pass it a mongo query that defines the users you want to ignore
+    AARRR.ignored_cohort :googlebot, "data.useragent" => /googlebot/
+
+
+## Pulling the Data out (generating reports)
+
+AARRR provides some simple views that allow you to generate some basic reports. Reports are generated via a cron job `rake aarrr:generate`.
+
+You can also generate the reports manually by running AARRR.generate!, however I'd advise you to run it via Resque or Delayed Job as it may take a long time to generate.
+
+Once you have the reports, you can use the AARRR view helpers in order to render your reports to a web page.
+
+Our report views probably aren't going to be exactly what you want, so we encourage you to cycle through the `AAARR.report_results` (returns the latest generated report results) and build up your own graphs and charts.
+
+
+## Data Model
+
+This section describes how AARRR stores your data within the MongoDB collections (raw and reports).
+
+### Raw Events
+
+AARRR tracks the raw metric data in a 2 main tables:
+
+`aarrr_users`: tracks the unique identities of each user
+
+* `_id`: generated aarrr user id
+* `user_id`: optional tie in to your database's user_id (for drill down)
+* `data`: hash that stores any data that's passed for the user on creation. main use is for analyzing the cohort data
+* `splits`: hash that maps split testing rules to assigned splits for the user
+* `cohorts`: a hash that maps cohort rules with the results
+* `ignore_reason`: a string that represents the reason this user is ignored in reports
+* `referrer`: referrer url that user came from
+* `ip_address`: ip address for the user
+* `last_event_at`: date that the user last interacted with the site
+
+`aarrr_events`: tracks each event that the user is engaged in
+
+* `_id`: generated aarrr event id
+* `aarrr_user_id`: id that maps event back to the aarrr users table
+* `event_name`: name for the event that was tracked
+* `event_type`: category of event type you are tracking
+* `in_progress`: true/false whether or not this event_type is in progress (not yet completed)
+* `data`: data that should be tracked along with the event
+* `revenue`: revenue the was generated on this event
+* `referral_code`: referral code that was generated for this event
+
+
+### Reports
+
+... TBD ...
+
+

data/Rakefile

@@ -0,0 +1,43 @@
+require "bundler"
+Bundler.setup
+
+require 'rake'
+require 'rake/gempackagetask'
+
+gemspec = eval(File.read('aarrr.gemspec'))
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.gem_spec = gemspec
+end
+
+desc "build the gem and release it to rubygems.org"
+task :release => :gem do
+  puts "Tagging #{gemspec.version}..."
+  system "git tag -a #{gemspec.version} -m 'Tagging #{gemspec.version}'"
+  puts "Pushing to Github..."
+  system "git push --tags"
+  puts "Pushing to rubygems.org..."
+  system "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+require "rspec"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = "spec/**/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new('spec:progress') do |spec|
+  spec.rspec_opts = %w(--format progress)
+  spec.pattern = "spec/**/*_spec.rb"
+end
+
+require "rake/rdoctask"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "AARRR #{gemspec.version}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+
+task :default => :spec

data/aarrr.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |s|
+  s.name = "aarrr"
+  s.version = "0.0.1"
+
+  s.authors = ["Jacques Crocker"]
+  s.summary = "metrics for pirates"
+  s.description = "AARRR helps track user lifecycle metrics via MongoDB. It also provides cohort and reporting tools."
+
+  s.email = "railsjedi@gmail.com"
+  s.homepage = "http://github.com/railsjedi/aarrr"
+  s.rubyforge_project = "none"
+
+  s.require_paths = ["lib"]
+  s.files = Dir['lib/**/*',
+                'spec/**/*',
+                'aarrr.gemspec',
+                'Gemfile',
+                'Gemfile.lock',
+                'Guardfile',
+                'LICENSE',
+                'Rakefile',
+                'README.md']
+
+  s.test_files = Dir['spec/**/*']
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+
+  s.add_runtime_dependency "rack", ">= 1.2.2"
+  s.add_runtime_dependency "mongo", ">= 1.3.1"
+  s.add_development_dependency "rspec", ">= 2.0"
+end
+

data/lib/aarrr.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+require "mongo"
+require "aarrr/config"
+require "aarrr/session"
+
+require "rack"
+require "aarrr/middleware"
+
+# add railtie
+if defined?(Rails)
+  require "aarrr/railtie"
+end
+
+# helper method to initialize an AARRR session
+def AARRR(env_or_model)
+  if env_or_model.is_a?(Hash) and env_or_model["aarrr.session"]
+    env_or_model["aarrr.session"]
+  else
+    session = AARRR::Session.new(env_or_model)
+
+    # add to the rack env (if applicable)
+    env_or_model["aarrr.session"] = session if env_or_model.is_a?(Hash)
+
+    session
+  end
+
+end
+
+module AARRR
+
+  class << self
+
+    # Sets the Mongoid configuration options. Best used by passing a block.
+    #
+    # @example Set up configuration options.
+    #
+    #   AARRR.configure do |config|
+    #     config.database = Mongo::Connection.new.db("metrics")
+    #   end
+    #
+    # @return [ Config ] The configuration obejct.
+    def configure
+      config = AARRR::Config
+      block_given? ? yield(config) : config
+    end
+    alias :config :configure
+  end
+
+  # Take all the public instance methods from the Config singleton and allow
+  # them to be accessed through the AARRR module directly.
+  #
+  # @example Delegate the configuration methods.
+  #   AARRR.database = Mongo::Connection.new.db("test")
+  AARRR::Config.public_instance_methods(false).each do |name|
+    (class << self; self; end).class_eval <<-EOT
+      def #{name}(*args)
+        configure.send("#{name}", *args)
+      end
+    EOT
+  end
+
+end

data/lib/aarrr/config.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+
+module AARRR
+
+  # Configures AARRR
+  module Config
+    extend self
+    @settings = {}
+
+    @database = nil
+    @connection = nil
+
+    # Define a configuration option with a default.
+    #
+    # @example Define the option.
+    #   Config.option(:persist_in_safe_mode, :default => false)
+    #
+    # @param [ Symbol ] name The name of the configuration option.
+    # @param [ Hash ] options Extras for the option.
+    #
+    # @option options [ Object ] :default The default value.
+    #
+    def option(name, options = {})
+      define_method(name) do
+        @settings.has_key?(name) ? @settings[name] : options[:default]
+      end
+      define_method("#{name}=") { |value| @settings[name] = value }
+      define_method("#{name}?") { send(name) }
+    end
+
+    # default some options with defaults
+    option :database_name, :default => "metrics"
+    option :cookie_name, :default => "_utmarr"
+    option :cookie_expiration, :default => 60*24*60*60
+    option :user_collection_name, :default => "aarrr_users"
+    option :event_collection_name, :default => "aarrr_events"
+
+    # Get the Mongo::Connection to use to pull the AARRR metrics data
+    def connection
+      @connection || Mongo::Connection.new
+    end
+
+    # Set the Mongo::Connection to use to pull the AARRR metrics data
+    def connection=(connection)
+      @connection = connection
+    end
+
+    # Get the Mongo::Database associated with the AARRR metrics data
+    def database
+      @database || connection.db(database_name)
+    end
+
+    # Set the Mongo::Database associated with the AARRR metrics data
+    def database=(database)
+      @database = database
+    end
+
+    def users
+      database[user_collection_name]
+    end
+
+    def events
+      database[event_collection_name]
+    end
+
+  end
+
+end

data/lib/aarrr/middleware.rb

@@ -0,0 +1,21 @@
+module AARRR
+  class Middleware
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      aarrr_session = AARRR(env)
+
+      status, headers, body = @app.call(env)
+
+      # sets a tracking cookie on the response
+      response = Rack::Response.new body, status, headers
+      aarrr_session.save(response)
+
+      response.finish
+    end
+
+  end
+end

data/lib/aarrr/railtie.rb

@@ -0,0 +1,3 @@
+# encoding: utf-8
+
+# nothing yet...

data/lib/aarrr/session.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+
+module AARRR
+
+  # an AARR session is used to identify a particular user in order to track events
+  class Session
+    attr_accessor :id
+
+    # find or creates a session in the db based on the env or object
+    def initialize(env_or_object = nil, attributes = nil)
+      self.id = parse_id(env_or_object) || BSON::ObjectId.new.to_s
+
+      # perform upsert
+      update({"$set" => build_attributes(env_or_object).merge(attributes || {})}, :upsert => true)
+    end
+
+    # returns a reference the othe AARRR user
+    def user
+      AARRR.users.find(id)
+    end
+
+    # sets some additional data
+    def set_data(data)
+      update({"data" => {"$set" => data}})
+    end
+
+    # save a cookie to the response
+    def save(response)
+      response.set_cookie(AARRR::Config.cookie_name, {
+        :value => self.id,
+        :path => "/",
+        :expires => Time.now+AARRR::Config.cookie_expiration
+      })
+    end
+
+    # track event name
+    def track!(event_name, options = {})
+
+      # add event tracking
+      result = AARRR.events.insert({
+        "aarrr_user_id" => self.id,
+        "event_name" => event_name,
+        "event_type" => options[:event_type],
+        "in_progress" => options[:in_progress] || false,
+        "data" => options[:data],
+        "revenue" => options[:revenue],
+        "referral_code" => options[:referral_code]
+      })
+
+      # update user with last updated time
+      update({
+        "$set" => {
+          "last_event_at" => Time.now.getutc
+        }
+      })
+
+      result
+    end
+
+    # more helpers
+
+    def acquisition!(event_name, options = {})
+      options[:event_type] = :acquisition
+      track!(event_name, options)
+    end
+
+    def activation!(event_name, options = {})
+      options[:event_type] = :activation
+      track!(event_name, options)
+    end
+
+    def retention!(event_name, options = {})
+      options[:event_type] = :retention
+      track!(event_name, options)
+    end
+
+    # TODO: referral and revenue
+
+
+    protected
+
+    # mark update
+    def update(attributes, options = {})
+      AARRR.users.update({"_id" => id}, attributes, options)
+    end
+
+    # returns id
+    def parse_id(env_or_object)
+      # check for empty case or string
+
+      # if it's a hash, then process like a request and pull out the cookie
+      if env_or_object.is_a?(Hash)
+
+        request = Rack::Request.new(env_or_object)
+        request.cookies[AARRR::Config.cookie_name]
+
+      # if it's an object with an id, then return that
+      elsif env_or_object.respond_to?(:id) and env_or_object.id.is_a?(BSON::ObjectId)
+        env_or_object.id.to_s
+
+      # if it's a string
+      elsif env_or_object.is_a?(String)
+        env_or_object
+
+      end
+    end
+
+    # returns updates
+    def build_attributes(env_or_object)
+      if env_or_object.is_a?(Hash)
+        user_attributes = {}
+
+        # referrer: HTTP_REFERER
+        referrer = env_or_object["HTTP_REFERER"]
+        user_attributes["referrer"] = referrer if referrer
+
+        # ip_address: HTTP_X_REAL_IP || REMOTE_ADDR
+        ip_address = env_or_object["HTTP_X_REAL_IP"] || env_or_object["REMOTE_ADDR"]
+        user_attributes["ip_address"] = ip_address if ip_address
+
+        # TODO: additional data from the env for the user
+
+        user_attributes
+      else
+        {}
+      end
+    end
+
+  end
+end

data/spec/functional/aarrr/config_spec.rb

@@ -0,0 +1,2 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+

data/spec/functional/aarrr/session_spec.rb

@@ -0,0 +1,55 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+require 'rack'
+
+module AARRR
+  describe Session do
+
+    describe "#new" do
+      it "should create a session with no data" do
+        session = Session.new
+        AARRR.users.count.should eq(1)
+      end
+
+      it "should create a session with a request env" do
+        session = Session.new
+        Session.new({
+          "HTTP_COOKIE" => "_utmarr=#{session.id}; path=/;"
+        })
+        AARRR.users.count.should eq(1)
+
+        session = Session.new({
+          "HTTP_COOKIE" => "_utmarr=x83y1; path=/;"
+        })
+
+        AARRR.users.count.should eq(2)
+      end
+    end
+
+    describe "tracking" do
+      before(:each) do
+        @session = Session.new
+      end
+
+      it "should track a custom event" do
+        @session.track!(:something)
+
+        AARRR.events.count.should eq(1)
+      end
+    end
+
+    describe "saving" do
+      it "should save the session to cookie" do
+        @session = Session.new
+        @session.track!(:some_event)
+
+        # save session to response
+        response = Rack::Response.new "some body", 200, {}
+        @session.save(response)
+
+        response.header["Set-Cookie"].should include("_utmarr=#{@session.id}")
+      end
+    end
+
+  end
+end

data/spec/functional/aarrr_spec.rb

@@ -0,0 +1,27 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe "spec setup" do
+  it "should run the specs without error" do
+    true.should be_true
+  end
+end
+
+describe "AARRR()" do
+
+  context "with an request.env" do
+    before(:each) do
+      @env = {}
+      AARRR(@env)
+    end
+
+    it "should create a session" do
+      AARRR.users.count.should eq(1)
+    end
+
+    it "should set the aarrr.session env variable" do
+      user_attributes = AARRR.users.find_one
+      @env["aarrr.session"].id.should eq(user_attributes["_id"])
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+require 'bundler/setup'
+require 'aarrr'
+
+RSpec.configure do |config|
+
+  config.before(:suite) do
+    # setup the AARRR test database
+    AARRR.configure do |c|
+      puts "configured to use aarrr_metrics_test db"
+      c.database_name = "aarrr_metrics_test"
+    end
+  end
+
+  config.before(:each) do
+    AARRR.database.collections.select {|c| c.name !~ /system/ }.each(&:drop)
+  end
+
+  # add helper methods here
+
+end
+

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: aarrr
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jacques Crocker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-02 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mongo
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2.0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+description: AARRR helps track user lifecycle metrics via MongoDB. It also provides cohort and reporting tools.
+email: railsjedi@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- lib/aarrr/config.rb
+- lib/aarrr/middleware.rb
+- lib/aarrr/railtie.rb
+- lib/aarrr/session.rb
+- lib/aarrr.rb
+- spec/functional/aarrr/config_spec.rb
+- spec/functional/aarrr/session_spec.rb
+- spec/functional/aarrr_spec.rb
+- spec/spec_helper.rb
+- aarrr.gemspec
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE
+- Rakefile
+- README.md
+has_rdoc: true
+homepage: http://github.com/railsjedi/aarrr
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4480489648285763335
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4480489648285763335
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: none
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: metrics for pirates
+test_files: 
+- spec/functional/aarrr/config_spec.rb
+- spec/functional/aarrr/session_spec.rb
+- spec/functional/aarrr_spec.rb
+- spec/spec_helper.rb