ahoy_matey 1.5.3 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 14b16720c567a2d253632b9a2a238273c1efb192
-  data.tar.gz: fa9aa63ecb5aaa91c44c9a617c4bccfa3f37f6c1
+SHA256:
+  metadata.gz: d90d64ae8641aa0bae1bc44acf29379a585ebbad0bbb87325380508d5a8ffcc7
+  data.tar.gz: 7c01ce8cbd2e92e3555479b251889d171b54be9d5c369fca51f413fdc912ab01
 SHA512:
-  metadata.gz: a77b0b9f3ba3bfd134f848a531406778a46ae213b532945b80e0e2d11e81019ee22d1c55b8967e1913dd5b01aa6814d2e0b512dc500fe7a856e5f33adad35455
-  data.tar.gz: 6f616904606aaf1af958a8defed7a2fd6ddf9297af5872a3746062ec74ce76cf8eb5c63c606ab45c10884d5119c6f3de45c1e618f892fa1495342a182b3adf28
+  metadata.gz: fe62cce407d17f736b616f11a742fefe338cdedd2457665cb3e578bafe0bd6fbb889dd315382dcb70d563a35dd5c5e05de908c069e12d21ab92e0cee637e42d7
+  data.tar.gz: f399c7708f6c1071c72db3d9164ab77bd3377fdc0eab7064707fb1202b240156be03669070763bf2f13bcf0bfcac134286eb9e9f9fb988d78267c71da9603386

data/CHANGELOG.md

@@ -1,3 +1,90 @@
+## 3.0.1
+
+- Made `Ahoy::Tracker` work outside of requests
+- Fixed storage of `false` values with customized store
+- Fixed error with `user_method` and `Rails::InfoController`
+- Gracefully handle `ActionDispatch::RemoteIp::IpSpoofAttackError`
+
+## 3.0.0
+
+- Made Device Detector the default user agent parser
+- Made v2 the default bot detection version
+- Removed a large number of dependencies
+- Removed search keyword detection (most search engines today prevent this)
+- Removed support for Rails < 5
+
+## 2.2.1
+
+- Updated Ahoy.js to 0.3.4
+- Fixed v2 bot detection
+- Added latitude and longitude to installation
+
+## 2.2.0
+
+- Added `amp_event` helper
+- Improved bot detection for Device Detector
+
+## 2.1.0
+
+- Added option for IP masking
+- Added option to use anonymity sets instead of cookies
+- Added `user_agent_parser` option
+- Fixed `visitable` for Rails 4.2
+- Removed `search_keyword` from new installs
+
+## 2.0.2
+
+- Fixed error on duplicate records
+- Fixed message when visit not found for geocoding
+- Better compatibility with GeoLite2
+- Better browser compatibility for Ahoy.js
+
+## 2.0.1
+
+- Added `Ahoy.server_side_visits = :when_needed` to automatically create visits server-side when needed for events and `visitable`
+- Better handling of visit duration and expiration in JavaScript
+
+## 2.0.0
+
+- Removed dependency on jQuery
+- Use `navigator.sendBeacon` by default in supported browsers
+- Added `geocode` event
+- Added `where_event` method for querying events
+- Added support for `visitable` and `where_props` to Mongoid
+- Added `preserve_callbacks` option
+- Use `json` for MySQL by default
+- Fixed log silencing
+
+Breaking changes
+
+- Simpler interface for data stores
+- Renamed `track_visits_immediately` to `server_side_visits` and enabled by default
+- Renamed `mount` option to `api` and disabled by default
+- Enabled `protect_from_forgery` by default
+- Removed deprecated options
+- Removed throttling
+- Removed most built-in stores
+- Removed support for Rails < 4.2
+
+## 1.6.1
+
+- Added `gin` index on properties for events
+- Fixed `visitable` options when name not provided
+
+## 1.6.0
+
+- Added support for Rails 5.1
+
+## 1.5.5
+
+- Added support for Rails API
+- Added NATS and NSQ stores
+
+## 1.5.4
+
+- Fixed issue with duplicate events
+- Added support for PostGIS for `where_properties`
+
 ## 1.5.3
 
 - Fixed error with Rails 5 and Mongoid 6
@@ -36,6 +123,7 @@
 - Detect database for `rails g ahoy:stores:active_record` for easier installation
 - Use `safely` as default exception handler
 - Fixed issue with log silencer
+- Use multi-column indexes on `ahoy_events` table creation
 
 ## 1.3.1
 

data/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+First, thanks for wanting to contribute. You’re awesome! :heart:
+
+## Help
+
+We’re not able to provide support through GitHub Issues. If you’re looking for help with your code, try posting on [Stack Overflow](https://stackoverflow.com/).
+
+All features should be documented. If you don’t see a feature in the docs, assume it doesn’t exist.
+
+## Bugs
+
+Think you’ve discovered a bug?
+
+1. Search existing issues to see if it’s been reported.
+2. Try the `master` branch to make sure it hasn’t been fixed.
+
+```rb
+gem "ahoy_matey", github: "ankane/ahoy"
+```
+
+If the above steps don’t help, create an issue. Include:
+
+- Detailed steps to reproduce
+- Complete backtraces for exceptions
+
+## New Features
+
+If you’d like to discuss a new feature, create an issue and start the title with `[Idea]`.
+
+## Pull Requests
+
+Fork the project and create a pull request. A few tips:
+
+- Keep changes to a minimum. If you have multiple features or fixes, submit multiple pull requests.
+- Follow the existing style. The code should read like it’s written by a single person.
+
+Feel free to open an issue to get feedback on your idea before spending too much time on it.
+
+---
+
+This contributing guide is released under [CCO](https://creativecommons.org/publicdomain/zero/1.0/) (public domain). Use it for your own project without attribution.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Andrew Kane
+Copyright (c) 2014-2019 Andrew Kane
 
 MIT License
 

data/README.md

@@ -1,10 +1,14 @@
 # Ahoy
 
-Ahoy provides a solid foundation to track visits and events in Ruby, JavaScript, and native apps. Works with any data store so you can easily scale.
+:fire: Simple, powerful analytics for Rails
+
+Track visits and events in Ruby, JavaScript, and native apps. Data is stored in your database by default so you can easily combine it with other data.
+
+:postbox: To track emails, check out [Ahoy Email](https://github.com/ankane/ahoy_email), and for A/B testing, check out [Field Test](https://github.com/ankane/field_test)
 
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
-:postbox: To track emails, check out [Ahoy Email](https://github.com/ankane/ahoy_email).
+[![Build Status](https://travis-ci.org/ankane/ahoy.svg?branch=master)](https://travis-ci.org/ankane/ahoy)
 
 ## Installation
 
@@ -14,159 +18,124 @@ Add this line to your application’s Gemfile:
 gem 'ahoy_matey'
 ```
 
-And add the javascript file in `app/assets/javascripts/application.js` after jQuery.
-
-```javascript
-//= require jquery
-//= require ahoy
-```
-
-## Choose a Data Store
-
-Ahoy supports a number of data stores out of the box.  You can start with one of them and customize as needed, or create your own store from scratch.
-
-- [PostgreSQL, MySQL, or SQLite](#postgresql-mysql-or-sqlite)
-- [MongoDB](#mongodb)
-- [Kafka](#kafka)
-- [Fluentd](#fluentd)
-- [RabbitMQ](#rabbitmq)
-- [Amazon Kinesis Firehose](#amazon-kinesis-firehose)
-- [Logs](#logs)
-- [Custom](#custom)
-
-### PostgreSQL, MySQL, or SQLite
-
-Run:
+And run:
 
 ```sh
-rails generate ahoy:stores:active_record
-rake db:migrate
+bundle install
+rails generate ahoy:install
+rails db:migrate
 ```
 
-### MongoDB
+Restart your web server, open a page in your browser, and a visit will be created :tada:
 
-```sh
-rails generate ahoy:stores:mongoid
+Track your first event from a controller with:
+
+```ruby
+ahoy.track "My first event", language: "Ruby"
 ```
 
-### Kafka
+### JavaScript, Native Apps, & AMP
 
-Add [ruby-kafka](https://github.com/zendesk/ruby-kafka) to your Gemfile.
+Enable the API in `config/initializers/ahoy.rb`:
 
 ```ruby
-gem 'ruby-kafka'
+Ahoy.api = true
 ```
 
-And run:
+And restart your web server.
+
+### JavaScript
+
+For Rails 6 / Webpacker, run:
 
 ```sh
-rails generate ahoy:stores:kafka
+yarn add ahoy.js
 ```
 
-Use `ENV["KAFKA_URL"]` to configure.
+And add to `app/javascript/packs/application.js`:
 
-### Fluentd
+```javascript
+import ahoy from "ahoy.js";
+```
 
-Add [fluent-logger](https://github.com/fluent/fluent-logger-ruby) to your Gemfile.
+For Rails 5 / Sprockets, add to `app/assets/javascripts/application.js`:
 
-```ruby
-gem 'fluent-logger'
+```javascript
+//= require ahoy
 ```
 
-And run:
+Track an event with:
 
-```sh
-rails generate ahoy:stores:fluentd
+```javascript
+ahoy.track("My second event", {language: "JavaScript"});
 ```
 
-Use `ENV["FLUENTD_HOST"]` and `ENV["FLUENTD_PORT"]` to configure.
+### GDPR Compliance
 
-### RabbitMQ
+Ahoy provides a number of options to help with GDPR compliance. See the [GDPR section](#gdpr-compliance-1) for more info.
 
-Add [bunny](https://github.com/ruby-amqp/bunny) to your Gemfile.
-
-```ruby
-gem 'bunny'
-```
+## How It Works
 
-And run:
+### Visits
 
-```sh
-rails generate ahoy:stores:bunny
-```
+When someone visits your website, Ahoy creates a visit with lots of useful information.
 
-Use `ENV["RABBITMQ_URL"]` to configure.
+- **traffic source** - referrer, referring domain, landing page
+- **location** - country, region, city, latitude, longitude
+- **technology** - browser, OS, device type
+- **utm parameters** - source, medium, term, content, campaign
 
-### Amazon Kinesis Firehose
+Use the `current_visit` method to access it.
 
-Add [aws-sdk](https://github.com/aws/aws-sdk-ruby) to your Gemfile.
+Prevent certain Rails actions from creating visits with:
 
 ```ruby
-gem 'aws-sdk', '>= 2.0.0'
+skip_before_action :track_ahoy_visit
 ```
 
-And run:
+This is typically useful for APIs. If your entire Rails app is an API, you can use:
 
-```sh
-rails generate ahoy:stores:kinesis_firehose
+```ruby
+Ahoy.api_only = true
 ```
 
-Configure delivery streams and credentials in the initializer.
+You can also defer visit tracking to JavaScript. This is useful for preventing bots (that aren’t detected by their user agent) and users with cookies disabled from creating a new visit on each request. `:when_needed` will create visits server-side only when needed by events, and `false` will disable server-side creation completely, discarding events without a visit.
 
-### Logs
-
-```sh
-rails generate ahoy:stores:log
+```ruby
+Ahoy.server_side_visits = :when_needed
 ```
 
-This logs visits to `log/visits.log` and events to `log/events.log`.
+### Events
 
-### Custom
+Each event has a `name` and `properties`. There are several ways to track events.
 
-```sh
-rails generate ahoy:stores:custom
+#### Ruby
+
+```ruby
+ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
 ```
 
-This creates a class for you to fill out.
+Track actions automatically with:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::BaseStore
-  def track_visit(options)
-  end
+class ApplicationController < ActionController::Base
+  after_action :track_action
 
-  def track_event(name, properties, options)
+  protected
+
+  def track_action
+    ahoy.track "Ran action", request.path_parameters
   end
 end
 ```
 
-See the [ActiveRecordTokenStore](https://github.com/ankane/ahoy/blob/master/lib/ahoy/stores/active_record_token_store.rb) for an example.
-
-## How It Works
-
-### Visits
-
-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.
-
-### 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:
+Track events automatically with:
 
 ```javascript
 ahoy.trackAll();
@@ -174,140 +143,155 @@ ahoy.trackAll();
 
 See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
 
-#### Ruby
-
-```ruby
-ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
-```
-
 #### Native Apps
 
-See the [HTTP spec](#native-apps-1) until libraries are built.
+For Android, check out [Ahoy Android](https://github.com/instacart/ahoy-android). For other platforms, see the [API spec](#api-spec).
 
-### Users
+#### AMP
 
-Ahoy automatically attaches the `current_user` to the visit.
+```erb
+<head>
+  <script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script>
+</head>
+<body>
+  <%= amp_event "Viewed article", title: "Analytics with Rails" %>
+</body>
+```
 
-With [Devise](https://github.com/plataformatec/devise), it will attach the user even if he or she signs in after the visit starts.
+### Associated Models
 
-With other authentication frameworks, add this to the end of your sign in method:
+Say we want to associate orders with visits. Just add `visitable` to the model.
 
 ```ruby
-ahoy.authenticate(user)
+class Order < ApplicationRecord
+  visitable :ahoy_visit
+end
 ```
 
-## Customize the Store
+When a visitor places an order, the `ahoy_visit_id` column is automatically set :tada:
 
-Stores are built to be highly customizable.
+See where orders are coming from with simple joins:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  # add methods here
-end
+Order.joins(:ahoy_visit).group("referring_domain").count
+Order.joins(:ahoy_visit).group("city").count
+Order.joins(:ahoy_visit).group("device_type").count
 ```
 
-### Exclude Bots and More
-
-Exclude visits and events from being tracked with:
+Here’s what the migration to add the `ahoy_visit_id` column should look like:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def exclude?
-    bot? || request.ip == "192.168.1.1"
+class AddVisitIdToOrders < ActiveRecord::Migration[6.0]
+  def change
+    add_column :orders, :ahoy_visit_id, :bigint
   end
 end
 ```
 
-Bots are excluded by default.
-
-### Track Additional Values
+Customize the column with:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def track_visit(options)
-    super do |visit|
-      visit.gclid = visit_properties.landing_params["gclid"]
-    end
-  end
-
-  def track_event(name, properties, options)
-    super do |event|
-      event.ip = request.ip
-    end
-  end
-end
+visitable :sign_up_visit
 ```
 
-Some methods you can use are `request`, `controller`, `visit_properties`, and `ahoy`.
+### Users
 
-### Customize User
+Ahoy automatically attaches the `current_user` to the visit. With [Devise](https://github.com/plataformatec/devise), it attaches the user even if he or she signs in after the visit starts.
 
-If you use a method other than `current_user`, set it here:
+With other authentication frameworks, add this to the end of your sign in method:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def user
-    controller.true_user
-  end
+ahoy.authenticate(user)
+```
+
+To see the visits for a given user, create an association:
+
+```ruby
+class User < ApplicationRecord
+  has_many :visits, class_name: "Ahoy::Visit"
 end
 ```
 
-### Report Exceptions
+And use:
+
+```ruby
+User.find(123).visits
+```
 
-Exceptions are rescued so analytics do not break your app. Ahoy uses [Safely](https://github.com/ankane/safely) to try to report them to a service by default.
+#### Custom User Method
 
-To customize this, use:
+Use a method besides `current_user`
 
 ```ruby
-Safely.report_exception_method = proc { |e| Rollbar.error(e) }
+Ahoy.user_method = :true_user
 ```
 
-### Use Different Models
+or use a proc
+
+```ruby
+Ahoy.user_method = ->(controller) { controller.true_user }
+```
 
-For ActiveRecord and Mongoid stores
+#### Doorkeeper
+
+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 Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def visit_model
-    CustomVisit
-  end
+class ApplicationController < ActionController::Base
+  private
 
-  def event_model
-    CustomEvent
+  def current_resource_owner
+    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
   end
 end
 ```
 
-## More Features
+#### Knock
 
-### Automatic Tracking
+To attach the user with [Knock](https://github.com/nsarno/knock), either include `Knock::Authenticable`in `ApplicationController`:
 
-Page views
+```ruby
+class ApplicationController < ActionController::API
+  include Knock::Authenticable
+end
+```
 
-```javascript
-ahoy.trackView();
+Or include it in Ahoy:
+
+```ruby
+Ahoy::BaseController.include Knock::Authenticable
 ```
 
-Clicks
+And use:
 
-```javascript
-ahoy.trackClicks();
+```ruby
+Ahoy.user_method = ->(controller) { controller.send(:authenticate_entity, "user") }
 ```
 
-Rails actions
+### Exclusions
+
+Bots are excluded from tracking by default. To include them, use:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  after_action :track_action
+Ahoy.track_bots = true
+```
 
-  protected
+Add your own rules with:
 
-  def track_action
-    ahoy.track "Processed #{controller_name}##{action_name}", request.filtered_parameters
-  end
+```ruby
+Ahoy.exclude_method = lambda do |controller, request|
+  request.ip == "192.168.1.1"
 end
 ```
 
+### Visit Duration
+
+By default, a new visit is created after 4 hours of inactivity. Change this with:
+
+```ruby
+Ahoy.visit_duration = 30.minutes
+```
+
 ### Multiple Subdomains
 
 To track visits across multiple subdomains, use:
@@ -316,103 +300,136 @@ To track visits across multiple subdomains, use:
 Ahoy.cookie_domain = :all
 ```
 
-### Visit Duration
+### Geocoding
+
+Disable geocoding with:
 
-By default, a new visit is created after 4 hours of inactivity.
+```ruby
+Ahoy.geocode = false
+```
 
-Change this with:
+Change the job queue with:
 
 ```ruby
-Ahoy.visit_duration = 30.minutes
+Ahoy.job_queue = :low_priority
 ```
 
-### ActiveRecord
+#### Geocoding Performance
 
-Let’s associate orders with visits.
+To avoid calls to a remote API, download the [GeoLite2 City database](https://dev.maxmind.com/geoip/geoip2/geolite2/) and configure Geocoder to use it.
 
-First, generate a migration and add a `visit_id` column.
+Add this line to your application’s Gemfile:
 
 ```ruby
-class AddVisitIdToOrders < ActiveRecord::Migration
-  def change
-    add_column :orders, :visit_id, :integer
-  end
-end
+gem 'maxminddb'
 ```
 
-**Note**: Use the `uuid` column type if the `id` column on `visits` is a `uuid`.
-
-Then, add `visitable` to the model.
+And create an initializer at `config/initializers/geocoder.rb` with:
 
 ```ruby
-class Order < ActiveRecord::Base
-  visitable
-end
+Geocoder.configure(
+  ip_lookup: :geoip2,
+  geoip2: {
+    file: Rails.root.join("lib", "GeoLite2-City.mmdb")
+  }
+)
 ```
 
-When a visitor places an order, the `visit_id` column is automatically set. :tada:
+If you use Heroku, you can use an unofficial buildpack like [this one](https://github.com/temedica/heroku-buildpack-maxmind-geolite2) to avoid including the database in your repo.
 
-Customize the column and class name with:
+### Token Generation
+
+Ahoy uses random UUIDs for visit and visitor tokens by default, but you can use your own generator like [Druuid](https://github.com/recurly/druuid).
 
 ```ruby
-visitable :sign_up_visit, class_name: "Visit"
+Ahoy.token_generator = -> { Druuid.gen }
 ```
 
-### Doorkeeper
+### Throttling
 
-To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
+You can use [Rack::Attack](https://github.com/kickstarter/rack-attack) to throttle requests to the API.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  private
-
-  def current_resource_owner
-    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
+class Rack::Attack
+  throttle("ahoy/ip", limit: 20, period: 1.minute) do |req|
+    if req.path.start_with?("/ahoy/")
+      req.ip
+    end
   end
 end
 ```
 
-### Geocoding
+### Exceptions
 
-By default, geocoding is performed inline. For performance, move it to the background with:
+Exceptions are rescued so analytics do not break your app. Ahoy uses [Safely](https://github.com/ankane/safely) to try to report them to a service by default. To customize this, use:
 
 ```ruby
-Ahoy.geocode = :async
+Safely.report_exception_method = ->(e) { Rollbar.error(e) }
 ```
 
-For Rails 4.0 and 4.1, you’ll need to add [activejob_backport](https://github.com/ankane/activejob_backport).
+## GDPR Compliance
+
+Ahoy provides a number of options to help with [GDPR compliance](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation).
 
-To change the queue name (`ahoy` by default), use:
+Update `config/initializers/ahoy.rb` with:
 
 ```ruby
-Ahoy.job_queue = :low_priority
+class Ahoy::Store < Ahoy::DatabaseStore
+  def authenticate(data)
+    # disables automatic linking of visits and users
+  end
+end
+
+Ahoy.mask_ips = true
+Ahoy.cookies = false
 ```
 
-Or disable geocoding with:
+This:
+
+- Masks IP addresses
+- Switches from cookies to anonymity sets
+- Disables automatic linking of visits and users
+
+If you use JavaScript tracking, also set:
+
+```javascript
+ahoy.configure({cookies: false});
+```
+
+### IP Masking
+
+Ahoy can mask IPs with the same approach [Google Analytics uses for IP anonymization](https://support.google.com/analytics/answer/2763052). This means:
+
+- For IPv4, the last octet is set to 0 (`8.8.4.4` becomes `8.8.4.0`)
+- For IPv6, the last 80 bits are set to zeros (`2001:4860:4860:0:0:0:0:8844` becomes `2001:4860:4860::`)
 
 ```ruby
-Ahoy.geocode = false
+Ahoy.mask_ips = true
 ```
 
-### Track Visits Immediately
+IPs are masked before geolocation is performed.
 
-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:
+To mask previously collected IPs, use:
 
 ```ruby
-Ahoy.track_visits_immediately = true
+Ahoy::Visit.find_each do |visit|
+  visit.update_column :ip, Ahoy.mask_ip(visit.ip)
+end
 ```
 
-**Note:** It’s highly recommended to perform geocoding in the background with this option.
+### Anonymity Sets & Cookies
 
-You can exclude API endpoints and other actions with:
+Ahoy can switch from cookies to [anonymity sets](https://privacypatterns.org/patterns/Anonymity-set). Instead of cookies, visitors with the same IP mask and user agent are grouped together in an anonymity set.
 
 ```ruby
-skip_before_action :track_ahoy_visit
+Ahoy.cookies = false
 ```
 
+Previously set cookies are automatically deleted.
+
 ## Development
 
-Ahoy is built with developers in mind.  You can run the following code in your browser’s console.
+Ahoy is built with developers in mind. You can run the following code in your browser’s console.
 
 Force a new visit
 
@@ -432,266 +449,238 @@ Turn off logging
 ahoy.debug(false);
 ```
 
-Debug endpoint requests in Ruby
+Debug API requests in Ruby
 
 ```ruby
 Ahoy.quiet = false
 ```
 
-## Explore the Data
-
-How you explore the data depends on the data store used.
-
-For SQL databases, you can use [Blazer](https://github.com/ankane/blazer) to easily generate charts and dashboards.
+## Data Stores
 
-With ActiveRecord, you can do:
+Data tracked by Ahoy is sent to your data store. Ahoy ships with a data store that uses your Rails database by default. You can find it in `config/initializers/ahoy.rb`:
 
 ```ruby
-Visit.group(:search_keyword).count
-Visit.group(:country).count
-Visit.group(:referring_domain).count
-```
-
-[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
-
-```erb
-<%= line_chart Visit.group_by_day(:started_at).count %>
+class Ahoy::Store < Ahoy::DatabaseStore
+end
 ```
 
-See where orders are coming from with simple joins:
+There are four events data stores can subscribe to:
 
 ```ruby
-Order.joins(:visit).group("referring_domain").count
-Order.joins(:visit).group("city").count
-Order.joins(:visit).group("device_type").count
-```
+class Ahoy::Store < Ahoy::BaseStore
+  def track_visit(data)
+    # new visit
+  end
 
-To see the visits for a given user, create an association:
+  def track_event(data)
+    # new event
+  end
 
-```ruby
-class User < ActiveRecord::Base
-  has_many :visits
+  def geocode(data)
+    # visit geocoded
+  end
+
+  def authenticate(data)
+    # user authenticates
+  end
 end
 ```
 
-And use:
+Data stores are designed to be highly customizable so you can scale as you grow. Check out [examples](docs/Data-Store-Examples.md) for Kafka, RabbitMQ, Fluentd, NATS, NSQ, and Amazon Kinesis Firehose.
 
-```ruby
-user = User.first
-user.visits
-```
-
-### Create Funnels
+### Track Additional Data
 
 ```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)
+class Ahoy::Store < Ahoy::DatabaseStore
+  def track_visit(data)
+    data[:accept_language] = request.headers["Accept-Language"]
+    super(data)
+  end
+end
 ```
 
-The same approach also works with visitor tokens.
+Two useful methods you can use are `request` and `controller`.
 
-### Querying Properties
+You can pass additional visit data from JavaScript with:
 
-With ActiveRecord, use:
-
-```ruby
-Ahoy::Event.where(name: "Viewed product").where_properties(product_id: 123).count
+```javascript
+ahoy.configure({visitParams: {referral_code: 123}});
 ```
 
-**Note:** If you get a `NoMethodError`, upgrade Ahoy and add `include Ahoy::Properties` to the Ahoy::Event class:
+And use:
 
 ```ruby
-module Ahoy
-  class Event < ActiveRecord::Base
-    include Ahoy::Properties
-    ...
+class Ahoy::Store < Ahoy::DatabaseStore
+  def track_visit(data)
+    data[:referral_code] = request.parameters[:referral_code]
+    super(data)
   end
 end
 ```
 
-## Native Apps
-
-### Visits
-
-When a user launches the app, create a visit.
-
-Generate a `visit_token` and `visitor_token` as [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier).
-
-Send these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
-
-Send a `POST` request to `/ahoy/visits` with:
-
-- platform - `iOS`, `Android`, etc.
-- app_version - `1.0.0`
-- os_version - `7.0.6`
-
-After 4 hours of inactivity, create another visit and use the updated visit id.
-
-### Events
+### Use Different Models
 
-Send a `POST` request as `Content-Type: application/json` to `/ahoy/events` with:
+```ruby
+class Ahoy::Store < Ahoy::DatabaseStore
+  def visit_model
+    MyVisit
+  end
 
-- 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)
+  def event_model
+    MyEvent
+  end
+end
+```
 
-Use an array to pass multiple events at once.
+## Explore the Data
 
-## Reference
+[Blazer](https://github.com/ankane/blazer) is a great tool for exploring your data.
 
-By default, Ahoy create endpoints at `/ahoy/visits` and `/ahoy/events`. To disable, use:
+With ActiveRecord, you can do:
 
 ```ruby
-Ahoy.mount = false
+Ahoy::Visit.group(:search_keyword).count
+Ahoy::Visit.group(:country).count
+Ahoy::Visit.group(:referring_domain).count
 ```
 
-## Upgrading
+[Chartkick](https://www.chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
 
-### 1.4.0
+```erb
+<%= line_chart Ahoy::Visit.group_by_day(:started_at).count %>
+```
 
-There’s nothing to do, but it’s worth noting the default store was changed from `ActiveRecordStore` to `ActiveRecordTokenStore` for new installations. `ActiveRecordStore` will continue to be supported.
+### Querying Events
 
-### json -> jsonb
+Ahoy provides two methods on the event model to make querying easier.
 
-Create a migration to add a new `jsonb` column.
+To query on both name and properties, you can use:
 
 ```ruby
-rename_column :ahoy_events, :properties, :properties_json
-add_column :ahoy_events, :properties, :jsonb
+Ahoy::Event.where_event("Viewed product", product_id: 123).count
 ```
 
-Restart your web server immediately afterwards, as Ahoy will rescue and report errors until then.
-
-Sync the new column.
+Or just query properties with:
 
 ```ruby
-Ahoy::Event.where(properties: nil).select(:id).find_in_batches do |events|
-  Ahoy::Event.where(id: events.map(&:id)).update_all("properties = properties_json::jsonb")
-end
+Ahoy::Event.where_props(product_id: 123).count
 ```
 
-Then create a migration to drop the old column.
+### Funnels
+
+It’s easy to create funnels.
 
 ```ruby
-remove_column :ahoy_events, :properties_json
+viewed_store_ids = Ahoy::Event.where(name: "Viewed store").distinct.pluck(:user_id)
+added_item_ids = Ahoy::Event.where(user_id: viewed_store_ids, name: "Added item to cart").distinct.pluck(:user_id)
+viewed_checkout_ids = Ahoy::Event.where(user_id: added_item_ids, name: "Viewed checkout").distinct.pluck(:user_id)
 ```
 
-### 1.0.0
+The same approach also works with visitor tokens.
 
-Add the following code to the end of `config/intializers/ahoy.rb`.
+## Tutorials
 
-```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  uses_deprecated_subscribers
-end
-```
+- [Tracking Metrics with Ahoy and Blazer](https://gorails.com/episodes/internal-metrics-with-ahoy-and-blazer)
 
-If you use `Ahoy::Event` to track events, copy it into your project.
+## API Spec
 
-```ruby
-module Ahoy
-  class Event < ActiveRecord::Base
-    self.table_name = "ahoy_events"
+### Visits
 
-    belongs_to :visit
-    belongs_to :user, polymorphic: true
+Generate visit and visitor tokens as [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier), and include these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
 
-    serialize :properties, JSON
-  end
-end
-```
+Send a `POST` request to `/ahoy/visits` with `Content-Type: application/json` and a body like:
 
-That’s it!  To fix deprecations, keep reading.
+```json
+{
+  "visit_token": "<visit-token>",
+  "visitor_token": "<visitor-token>",
+  "platform": "iOS",
+  "app_version": "1.0.0",
+  "os_version": "11.2.6"
+}
+```
 
-#### Visits
+After 4 hours of inactivity, create another visit (use the same visitor token).
 
-Remove `ahoy_visit` from your visit model and replace it with:
+### Events
 
-```ruby
-class Visit < ActiveRecord::Base
-  belongs_to :user, polymorphic: true
-end
+Send a `POST` request to `/ahoy/events` with `Content-Type: application/json` and a body like:
+
+```json
+{
+  "visit_token": "<visit-token>",
+  "visitor_token": "<visitor-token>",
+  "events": [
+    {
+      "id": "<optional-random-id>",
+      "name": "Viewed item",
+      "properties": {
+        "item_id": 123
+      },
+      "time": "2018-01-01T00:00:00-07:00"
+    }
+  ]
+}
 ```
 
-#### Subscribers
+## Upgrading
 
-Remove `uses_deprecated_subscribers` from `Ahoy::Store`.
+### 3.0
 
-If you have a custom subscriber, copy the `track` method to `track_event` in `Ahoy::Store`.
+If you installed Ahoy before 2.1 and want to keep legacy user agent parsing and bot detection, add to your Gemfile:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def track_event(name, properties, options)
-    # code copied from the track method in your subscriber
-  end
-end
+gem "browser", "~> 2.0"
+gem "user_agent_parser"
 ```
 
-#### Authentication
-
-Ahoy no longer tracks the `$authenticate` event automatically.
-
-To restore this behavior, use:
+And add to `config/initializers/ahoy.rb`:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def authenticate(user)
-    super
-    ahoy.track "$authenticate"
-  end
-end
+Ahoy.user_agent_parser = :legacy
 ```
 
-#### Global Options
+### 2.2
 
-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.
+Ahoy now ships with better bot detection if you use Device Detector. This should be more accurate but can significantly reduce the number of visits recorded. For existing installs, it’s opt-in to start. To use it, add to `config/initializers/ahoy.rb`:
 
 ```ruby
-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
+Ahoy.bot_detection_version = 2
 ```
 
-You made it!  Now, take advantage of Ahoy’s awesome new features, like easy customization and exception reporting.
-
-### 0.3.0
+### 2.1
 
-Starting with `0.3.0`, visit and visitor tokens are now UUIDs.
+Ahoy recommends [Device Detector](https://github.com/podigee/device_detector) for user agent parsing and makes it the default for new installations. To switch, add to `config/initializers/ahoy.rb`:
 
-### 0.1.6
+```ruby
+Ahoy.user_agent_parser = :device_detector
+```
 
-In `0.1.6`, a big improvement was made to `browser` and `os`. Update existing visits with:
+Backfill existing records with:
 
 ```ruby
-Visit.find_each do |visit|
-  visit.set_technology
-  visit.save! if visit.changed?
+Ahoy::Visit.find_each do |visit|
+  client = DeviceDetector.new(visit.user_agent)
+  device_type =
+    case client.device_type
+    when "smartphone"
+      "Mobile"
+    when "tv"
+      "TV"
+    else
+      client.device_type.try(:titleize)
+    end
+
+  visit.browser = client.name
+  visit.os = client.os_name
+  visit.device_type = device_type
+  visit.save(validate: false) if visit.changed?
 end
 ```
 
-## TODO
-
-- real-time dashboard of visits and events
-- more events for append only stores
-- turn off modules
-
-## No Ruby?
+### 2.0
 
-Check out [Ahoy.js](https://github.com/ankane/ahoy.js).
+See the [upgrade guide](docs/Ahoy-2-Upgrade.md)
 
 ## History