ahoy_matey 0.3.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2226bcc4712d1729f93cc68a4a01ac03eef2ee0a
-  data.tar.gz: fc0f05b5df70d3fddbb8f888bc7a136146b8cf47
+  metadata.gz: eee3fa6c02d811dff0ae4091ab08589366949211
+  data.tar.gz: 953da9d5b867bfb6c8abff089faa3ee06b965b0d
 SHA512:
-  metadata.gz: f1d5a9cff762a21c7690eabea4100b842fa419fb1b0094117e4d0f34500c131a9738a8c83f4d52ec397f8c951bbd7a99f55b6a837acc99f227d2457d528495a8
-  data.tar.gz: 047ed1ac5af0529aa172640629ca4101dff2659cc21452b4adb4f4d5219b684eae535d40f2d55b56ff9d0a65d440853bcf7bdf750da054afe2c4c004170fe2dd
+  metadata.gz: 4f37f8317be93f3c5192bdbc4b79fabdfa995d97da6385ad1eeb90074ea3ef8d9d4896e7f51ad4961e63f863d6269eb0fe8b59168d632db4de83b9ab158eb0ea
+  data.tar.gz: 402780cfd8f187c0f084562ae853678f18e43ce80b331e5820843e59b823e8733d12de0fd2d2c2413cde8ea596b9c474e36a9ec70c81f26aeb1c62f143aa1d05

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.0.0
+
+- Added support for any data store, and Mongoid out of the box
+- Added `track_visits_immediately` option
+- Added exception catching and reporting
+- Visits expire after inactivity, not fixed interval
+- Added `visit_duration` and `visitor_duration` options
+
 ## 0.3.2
 
 - Fixed bot exclusion for visits

data/README.md

@@ -2,26 +2,11 @@
 
 :fire: Simple, powerful analytics for Rails
 
-Visits are stored in **your database** so you can easily combine them with other data.
-
-You get:
-
-- **traffic source** - referrer, referring domain, landing page, search keyword
-- **location** - country, region, and city
-- **technology** - browser, OS, and device type
-- **utm parameters** - source, medium, term, content, campaign
-
-Track events in:
-
-- JavaScript
-- Ruby
-- Native apps
-
-And store them wherever you’d like - your database, logs, external services, or all of them.
+Ahoy makes it easy to track visitors and users.  Track visits (sessions) and events in Ruby, JavaScript, and native apps.  Works with any data store so you can easily scale.
 
 :postbox: To track emails, check out [Ahoy Email](https://github.com/ankane/ahoy_email).
 
-No Ruby? Check out [Ahoy.js](https://github.com/ankane/ahoy.js).
+See [upgrade instructions](#upgrading) on how to move to 1.0.
 
 ## Installation
 
@@ -31,202 +16,308 @@ Add this line to your application’s Gemfile:
 gem 'ahoy_matey'
 ```
 
-And run the generator. This creates a model to store visits.
+And add the javascript file in `app/assets/javascripts/application.js` after jQuery.
+
+```javascript
+//= require jquery
+//= require ahoy
+```
+
+## Choose a Data Store
+
+### ActiveRecord
+
+#### PostgreSQL
 
 ```sh
-rails generate ahoy:install
+rails generate ahoy:stores:active_record -d postgresql
 rake db:migrate
 ```
 
-Lastly, include the javascript file in `app/assets/javascripts/application.js` after jQuery.
+#### MySQL and SQLite
 
-```javascript
-//= require jquery
-//= require ahoy
+Add [activeuuid](https://github.com/jashmenn/activeuuid) to your Gemfile.
+
+```ruby
+gem 'activeuuid', '>= 0.5.0'
 ```
 
-We recommend using traditional analytics services like [Google Analytics](http://www.google.com/analytics/) as well.
+And run:
 
-## How It Works
+```sh
+rails generate ahoy:stores:active_record
+rake db:migrate
+```
 
-When someone visits your website, Ahoy creates a visit with lots of useful information.
+If you just want visits, run:
 
-Use the `current_visit` method to access it.
+```sh
+rails generate ahoy:stores:active_record_visits
+rake db:migrate
+```
 
-Explore your visits with queries like:
+### Mongoid
 
-```ruby
-Visit.group(:search_keyword).count
-Visit.group(:country).count
-Visit.group(:referring_domain).count
+```sh
+rails generate ahoy:stores:mongoid
 ```
 
-[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it super easy to visualize the data.
+### Logs
 
-```erb
-<%= line_chart Visit.group_by_day(:created_at).count %>
+```sh
+rails generate ahoy:stores:log
 ```
 
-### The Power
+This logs visits to `log/visits.log` and events to `log/events.log`.
 
-This information is great on its own, but super powerful when combined with other models.
+### Custom
 
-Let’s associate orders with visits.
+```sh
+rails generate ahoy:stores:custom
+```
+
+This creates a class for you to fill out.
 
 ```ruby
-class Order < ActiveRecord::Base
-  visitable
+class Ahoy::Store < Ahoy::Stores::BaseStore
+
+  def track_visit(options)
+  end
+
+  def track_event(name, properties, options)
+  end
+
 end
 ```
 
-When a visitor places an order, the `visit_id` column is automatically set.
+## How It Works
 
-:tada: Magic!
+### Visits
 
-See where orders are coming from with simple joins:
+When someone visits your website, Ahoy creates a visit with lots of useful information.
+
+- **traffic source** - referrer, referring domain, landing page, search keyword
+- **location** - country, region, and city
+- **technology** - browser, OS, and device type
+- **utm parameters** - source, medium, term, content, campaign
+
+Use the `current_visit` method to access it, and the `ahoy.visit_id` and `ahoy.visitor_id` methods to get the ids.
+
+### Events
+
+Each event has a `name` and `properties`.
+
+There are three ways to track events.
+
+#### JavaScript
+
+```javascript
+ahoy.track("Viewed book", {title: "The World is Flat"});
+```
+
+or track events automatically with:
+
+```javascript
+ahoy.trackAll();
+```
+
+See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
+
+#### Ruby
 
 ```ruby
-Order.joins(:visit).group("referring_domain").count
-Order.joins(:visit).group("city").count
-Order.joins(:visit).group("device_type").count
+ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
 ```
 
+#### Native Apps
+
+See the [HTTP spec](#native-apps) until libraries are built.
+
 ### Users
 
-Ahoy automatically attaches the `current_user` to the `current_visit`.
+Ahoy automatically attaches the `current_user` to the visit.
 
-With [Devise](https://github.com/plataformatec/devise), it will attach the user even if he / she signs in after the visit starts.
+With [Devise](https://github.com/plataformatec/devise), it will attach the user even if he or she signs in after the visit starts.
 
 With other authentication frameworks, add this to the end of your sign in method:
 
 ```ruby
-if current_visit and !current_visit.user
-  current_visit.user = current_user
-  current_visit.save!
-end
+ahoy.authenticate(user)
 ```
 
-To see the visits for a given user, create an association:
+## Customize the Store
+
+Stores are built to be highly customizable.
 
 ```ruby
-class User < ActiveRecord::Base
-  has_many :visits
+class Ahoy::Store < Ahoy::Stores::ActiveRecord
+  # add methods here
 end
 ```
 
-And use:
+### Exclude Bots and More
+
+Bots are excluded by default. To change this, use:
 
 ```ruby
-user = User.first
-user.visits
+def exclude?
+  bot? || request.ip == "192.168.1.1"
+end
 ```
 
-### UTM Parameters
+### Track Additional Values
 
-Use UTM parameters to track campaigns. [This is great for emails and social media](http://www.thunderseo.com/blog/utm-parameters/). Just add them to your links and Ahoy will pick them up.
-
-```
-http://datakick.org/?utm_medium=email&utm_campaign=newsletter&utm_source=newsletter-2014-03
+```ruby
+def track_visit(options)
+  super do |visit|
+    visit.gclid = visit_properties.landing_params["gclid"]
+  end
+end
 ```
 
 or
 
+```ruby
+def track_event(name, properties, options)
+  super do |event|
+    event.ip = request.ip
+  end
+end
 ```
-http://datakick.org/?utm_medium=twitter&utm_campaign=social&utm_source=tweet123
+
+### Customize User
+
+```ruby
+def user
+  controller.true_user
+end
 ```
 
-### Native Apps
+### Report Exceptions
 
-When a user launches the app, create a visit.  Send a `POST` request to `/ahoy/visits` with:
+Exceptions are caught by default so analytics do not break your app.
 
-- platform - `iOS`, `Android`, etc.
-- app_version - `1.0.0`
-- os_version - `7.0.6`
-- visit_token - `505f6201-8e10-44cf-ba1c-37271c8d0125`
-- visitor_token - `db3b1a8f-302b-42df-9cd0-06875f549474`
+To report them to a service, use:
 
-Tokens must be [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier).
+```ruby
+def report_exception(e)
+  Rollbar.report_exception(e)
+end
+```
 
-Send the visit and visitor tokens in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
+### Use Different Models
 
-After 4 hours, create another visit and use the updated visit token.
+For ActiveRecord and Mongoid stores
 
-## Events
+```ruby
+def visit_model
+  CustomVisit
+end
 
-Each event has a `name` and `properties`.
+def event_model
+  CustomEvent
+end
+```
 
-There are three ways to track events.
+## More Features
 
-#### JavaScript
+### Automatic Tracking
+
+Page views
 
 ```javascript
-ahoy.track("Viewed book", {title: "The World is Flat"});
+ahoy.trackView();
 ```
 
-or track all views and clicks with:
+Clicks
 
 ```javascript
-ahoy.trackAll();
+ahoy.trackClicks();
 ```
 
-See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
+Rails actions
 
-#### Ruby
+```ruby
+class ApplicationController < ActionController::Base
+  after_filter :track_action
+
+  protected
+
+  def track_action
+    ahoy.track "Processed #{controller_name}##{action_name}", request.filtered_parameters
+  end
+end
+```
+
+### Multiple Subdomains
+
+To track visits across multiple subdomains, use:
 
 ```ruby
-ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
+Ahoy.cookie_domain = :all
 ```
 
-#### Native Apps
+### Visit Duration
 
-Send a `POST` request to `/ahoy/events` with:
+By default, a new visit is created after 4 hours of inactivity.
 
-- name
-- properties
-- user token (depends on your authentication framework)
-- `Ahoy-Visit` header
+Change this with:
+
+```ruby
+Ahoy.visit_duration = 30.minutes
+```
 
-Requests should have `Content-Type: application/json`.
+### ActiveRecord
+
+Let’s associate orders with visits.
 
-### Storing Events
+```ruby
+class Order < ActiveRecord::Base
+  visitable
+end
+```
 
-You choose how to store events.
+When a visitor places an order, the `visit_id` column is automatically set.
 
-#### ActiveRecord
+:tada: Magic!
 
-Create an `Ahoy::Event` model to store events.
+Customize the column and class name with:
 
-```sh
-rails generate ahoy:events:active_record
-rake db:migrate
+```ruby
+visitable :sign_up_visit, class_name: "Visit"
 ```
 
-#### Custom
+### Doorkeeper
 
-Create your own subscribers in `config/initializers/ahoy.rb`.
+To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
 
 ```ruby
-class LogSubscriber
+class ApplicationController < ActionController::Base
+
+  private
 
-  def track(name, properties, options = {})
-    data = {
-      name: name,
-      properties: properties,
-      time: options[:time].to_i,
-      visit_id: options[:visit].try(:id),
-      user_id: options[:user].try(:id),
-      ip: options[:controller].try(:request).try(:remote_ip)
-    }
-    Rails.logger.info data.to_json
+  def current_resource_owner
+    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
   end
 
 end
+```
+
+### Track Visits Immediately
 
-# and add it
-Ahoy.subscribers << LogSubscriber.new
+Visitor and visit ids are generated on the first request (so you can use them immediately), but the `track_visit` method isn’t called until the JavaScript library posts to the server.  This prevents browsers with cookies disabled from creating multiple visits and ensures visits are not created for API endpoints.  Change this with:
+
+```ruby
+Ahoy.track_visits_immediately = true
 ```
 
-Add as many subscribers as you’d like.
+**Note:** At the moment, geocoding is performed in the foreground, which can slow down the first page load.
+
+You can exclude API endpoints and other actions with:
+
+```ruby
+skip_before_filter :track_ahoy_visit
+```
 
 ## Development
 
@@ -256,142 +347,183 @@ Debug endpoint requests in Ruby
 Ahoy.quiet = false
 ```
 
-### More
+## Explore the Data
 
-- Excludes bots
-- Degrades gracefully when cookies are disabled
-- Don’t need a field? Just remove it from the migration
-- Visits are 4 hours by default
+How you explore the data depends on the data store used.
 
-### Doorkeeper
-
-To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
+Here are ways to do it with ActiveRecord.
 
 ```ruby
-class ApplicationController < ActionController::Base
-
-  private
+Visit.group(:search_keyword).count
+Visit.group(:country).count
+Visit.group(:referring_domain).count
+```
 
-  def current_resource_owner
-    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
-  end
+[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it super easy to visualize the data.
 
-end
+```erb
+<%= line_chart Visit.group_by_day(:created_at).count %>
 ```
 
-## Reference
+See where orders are coming from with simple joins:
 
-To track visits across multiple subdomains, you must set the domain in two places (at the moment).
+```ruby
+Order.joins(:visit).group("referring_domain").count
+Order.joins(:visit).group("city").count
+Order.joins(:visit).group("device_type").count
+```
 
-Add this to the `config/initializers/ahoy.rb` initializer:
+To see the visits for a given user, create an association:
 
 ```ruby
-Ahoy.domain = "yourdomain.com"
+class User < ActiveRecord::Base
+  has_many :visits
+end
 ```
 
-and add this **before** the javascript files:
+And use:
 
-```javascript
-var ahoy = {"domain": "yourdomain.com"};
+```ruby
+user = User.first
+user.visits
 ```
 
-Change the platform on the web
+### Create Funnels
 
-```javascript
-var ahoy = {"platform": "Mobile Web"}
+```ruby
+viewed_store_ids = Ahoy::Event.where(name: "Viewed store").uniq.pluck(:user_id)
+added_item_ids = Ahoy::Event.where(user_id: viewed_store_ids, name: "Added item to cart").uniq.pluck(:user_id)
+viewed_checkout_ids = Ahoy::Event.where(user_id: added_item_ids, name: "Viewed checkout").uniq.pluck(:user_id)
 ```
 
-Track additional values
+The same approach also works with visitor ids.
 
-```ruby
-class Visit < ActiveRecord::Base
-  ahoy_visit
+## Native Apps
 
-  before_create :set_gclid
+### Visits
 
-  def set_gclid
-    self.gclid = landing_params["gclid"]
-  end
+When a user launches the app, create a visit.
 
-end
-```
+Generate a `visit_id` and `visitor_id` as [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier).
 
-Use a method besides `current_user`
+Send these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
 
-```ruby
-Ahoy.user_method = :true_user
-```
+Send a `POST` request to `/ahoy/visits` with:
 
-or use a Proc
+- platform - `iOS`, `Android`, etc.
+- app_version - `1.0.0`
+- os_version - `7.0.6`
 
-```ruby
-Ahoy.user_method = proc {|controller| controller.current_user }
-```
+After 4 hours of inactivity, create another visit and use the updated visit id.
 
-Customize visitable
+### Events
 
-```ruby
-visitable :sign_up_visit, class_name: "Visit"
-```
+Send a `POST` request as `Content-Type: application/json` to `/ahoy/events` with:
 
-Track view
+- id - `5aea7b70-182d-4070-b062-b0a09699ad5e` - UUID
+- name - `Viewed item`
+- properties - `{"item_id": 123}`
+- time - `2014-06-17T00:00:00-07:00` - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
+- `Ahoy-Visit` and `Ahoy-Visitor` headers
+- user token (depends on your authentication framework)
 
-```javascript
-ahoy.trackView();
-```
+Use an array to pass multiple events at once.
 
-Track clicks
+## Upgrading
 
-```javascript
-ahoy.trackClicks();
+### 1.0.0
+
+Add the following code to the end of `config/intializers/ahoy.rb`.
+
+```ruby
+class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
+  uses_deprecated_subscribers
+end
 ```
 
-Track all Rails actions
+If you use `Ahoy::Event` to track events, copy it into your project.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  after_filter :track_action
+module Ahoy
+  class Event < ActiveRecord::Base
+    self.table_name = "ahoy_events"
 
-  protected
+    belongs_to :visit
+    belongs_to :user, polymorphic: true
 
-  def track_action
-    ahoy.track "Hit action", request.filtered_parameters
+    serialize :properties, JSON
   end
 end
 ```
 
-Use a different model for visits
+That’s it!  To fix deprecations, keep reading.
 
-```ruby
-Ahoy.visit_model = UserVisit
+#### Visits
+
+Remove `ahoy_visit` from your visit model and replace it with:
 
-# fix for Rails reloader in development
-ActionDispatch::Reloader.to_prepare do
-  Ahoy.visit_model = UserVisit
+```ruby
+class Visit < ActiveRecord::Base
+  belongs_to :user, polymorphic: true
 end
 ```
 
-Use a different model for events
+#### Subscribers
+
+Remove `uses_deprecated_subscribers` from `Ahoy::Store`.
+
+If you have a custom subscriber, copy the `track` method to `track_event` in `Ahoy::Store`.
 
 ```ruby
-Ahoy.subscribers << Ahoy::Subscribers::ActiveRecord.new(model: Event)
+class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
+
+  def track_event(name, properties, options)
+    # code copied from the track method in your subscriber
+  end
+
+end
 ```
 
-Exclude visits and events
+#### Authentication
+
+Ahoy no longer tracks the `$authenticate` event automatically.
+
+To restore this behavior, use:
 
 ```ruby
-Ahoy.exclude_method = proc do |controller, request|
-  request.ip == "192.168.1.1"
+class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
+
+  def authenticate(user)
+    super
+    ahoy.track "$authenticate"
+  end
+
 end
 ```
 
-Track bots
+#### Global Options
+
+Replace the `Ahoy.user_method` with `user` method, and replace `Ahoy.track_bots` and `Ahoy.exclude_method` with `exclude?` method.
+
+Skip this step if you do not use these options.
 
 ```ruby
-Ahoy.track_bots = true
+class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
+
+  def user
+    # logic from Ahoy.user_method goes here
+    controller.true_user
+  end
+
+  def exclude?
+    # logic from Ahoy.track_bots and Ahoy.exclude_method goes here
+    bot? || request.ip == "192.168.1.1"
+  end
+
+end
 ```
 
-## Upgrading
+You made it!  Now, take advantage of Ahoy’s awesome new features, like easy customization and exception reporting.
 
 ### 0.3.0
 
@@ -410,10 +542,13 @@ end
 
 ## TODO
 
-- better readme
 - simple dashboard
 - turn off modules
 
+## No Ruby?
+
+Check out [Ahoy.js](https://github.com/ankane/ahoy.js).
+
 ## History
 
 View the [changelog](https://github.com/ankane/ahoy/blob/master/CHANGELOG.md)