ahoy_matey 2.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 47cc04adfac18b2f14547b376a3465f601d59307
-  data.tar.gz: 6e1638296155ceab46f9d105e52d7422259ebc63
+SHA256:
+  metadata.gz: 51e11f3086c12a1418ea7436e291ca9d2f0c7e0aa3091c48c904d05b4be6a210
+  data.tar.gz: 5b5c6afc94c0db23f2f1616f6e9edc0ae95ff334e33704c26417705d06d04670
 SHA512:
-  metadata.gz: 1f0a217bd790fff2b55e1e6395ea940079b2a457efc1328c61a054d6a3835f0d6fcb9c154eae7f3496f8a79559282cc3d9b1eefb2db4ce651d74d6c14dce536a
-  data.tar.gz: 6789de07f914f49b05f72b4b5517935571368be2e43987421e170dd8da838d78a1fa48e1d878424a9800f53ea779b5dcd8b3523432977f7aec4a29e296941a41
+  metadata.gz: fd75680d3d04b2383c30b19848f88fcb838f1498e8819d2d758aec6443e85bfb2f73a421da968cb54628097631c777ac1f95dd1ca4bae6d6b22d748a44dcb84d
+  data.tar.gz: 2d336bd12312cddf4b76f213b1f7f84b1fc2f0b67302e75096d1eb21013982f532064b31894ba217f7ccbafdbaf5eb4c691a3a86350b8abf1449374f66015909

data/CHANGELOG.md

@@ -1,4 +1,79 @@
-## 2.0.0
+## 3.2.0 (2021-03-01)
+
+- Disabled geocoding by default for new installations
+- Fixed deprecation warning with Active Record 6.1
+
+## 3.1.0 (2020-12-04)
+
+- Added `instance` method
+- Added `request` argument to `user_method`
+- Updated Ahoy.js to 0.3.8
+- Removed `exclude_method` call when geocoding
+
+## 3.0.5 (2020-09-09)
+
+- Added `group_prop` method
+- Use `datetime` type in migration
+
+## 3.0.4 (2020-06-07)
+
+- Updated Ahoy.js to 0.3.6
+
+## 3.0.3 (2020-04-17)
+
+- Updated Ahoy.js to 0.3.5
+
+## 3.0.2 (2020-04-03)
+
+- Added `cookie_options`
+
+## 3.0.1 (2019-09-21)
+
+- 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 (2019-05-29)
+
+- 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 (2019-05-26)
+
+- Updated Ahoy.js to 0.3.4
+- Fixed v2 bot detection
+- Added latitude and longitude to installation
+
+## 2.2.0 (2019-01-04)
+
+- Added `amp_event` helper
+- Improved bot detection for Device Detector
+
+## 2.1.0 (2018-05-18)
+
+- 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 (2018-03-14)
+
+- 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 (2018-02-26)
+
+- 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 (2018-02-25)
 
 - Removed dependency on jQuery
 - Use `navigator.sendBeacon` by default in supported browsers
@@ -20,58 +95,58 @@ Breaking changes
 - Removed most built-in stores
 - Removed support for Rails < 4.2
 
-## 1.6.1
+## 1.6.1 (2018-02-02)
 
 - Added `gin` index on properties for events
 - Fixed `visitable` options when name not provided
 
-## 1.6.0
+## 1.6.0 (2017-05-01)
 
 - Added support for Rails 5.1
 
-## 1.5.5
+## 1.5.5 (2017-03-23)
 
 - Added support for Rails API
 - Added NATS and NSQ stores
 
-## 1.5.4
+## 1.5.4 (2017-01-22)
 
 - Fixed issue with duplicate events
 - Added support for PostGIS for `where_properties`
 
-## 1.5.3
+## 1.5.3 (2016-10-31)
 
 - Fixed error with Rails 5 and Mongoid 6
 - Fixed regression with server not generating visit and visitor tokens
 - Accept UTM parameters as request parameters (for native apps)
 
-## 1.5.2
+## 1.5.2 (2016-08-26)
 
 - Better support for Rails 5
 
-## 1.5.1
+## 1.5.1 (2016-08-19)
 
 - Restored throttling after removing side effects
 
-## 1.5.0
+## 1.5.0 (2016-08-19)
 
 - Removed throttling due to unintended side effects with its implementation
 - Ensure basic token requirements
 - Fixed visit recreation on cookie expiration
 - Fixed issue where `/ahoy/visits` is called indefinitely when `Ahoy.cookie_domain = :all`
 
-## 1.4.2
+## 1.4.2 (2016-06-21)
 
 - Fixed issues with `where_properties`
 
-## 1.4.1
+## 1.4.1 (2016-06-20)
 
 - Added `where_properties` method
 - Added Kafka store
 - Added `mount` option
 - Use less intrusive version of `safely`
 
-## 1.4.0
+## 1.4.0 (2016-03-23)
 
 - Use `ActiveRecordTokenStore` by default (integer instead of uuid for id)
 - Detect database for `rails g ahoy:stores:active_record` for easier installation
@@ -79,55 +154,55 @@ Breaking changes
 - Fixed issue with log silencer
 - Use multi-column indexes on `ahoy_events` table creation
 
-## 1.3.1
+## 1.3.1 (2016-03-22)
 
 - Raise errors in test environment
 
-## 1.3.0
+## 1.3.0 (2016-03-06)
 
 - Added throttling
 - Added `max_content_length` and `max_events_per_request`
 
-## 1.2.2
+## 1.2.2 (2016-03-05)
 
 - Fixed issue with latest version of `browser` gem
 - Added support for RabbitMQ
 - Added support for Amazon Kinesis Firehose
 - Fixed deprecation warnings in Rails 5
 
-## 1.2.1
+## 1.2.1 (2015-08-14)
 
 - Fixed `SystemStackError: stack level too deep` when used with `activerecord-session_store`
 
-## 1.2.0
+## 1.2.0 (2015-06-07)
 
 - Added support for PostgreSQL `jsonb` column type
 - Added Fluentd store
 - Added latitude, longitude, and postal_code to visits
 - Log exclusions
 
-## 1.1.1
+## 1.1.1 (2015-01-05)
 
 - Better support for Authlogic
 - Added `screen_height` and `screen_width`
 
-## 1.1.0
+## 1.1.0 (2014-11-02)
 
 - Added `geocode` option
 - Report errors to service by default
 - Fixed association mismatch
 
-## 1.0.2
+## 1.0.2 (2014-07-10)
 
 - Fixed BSON for Mongoid 3
 - Fixed Doorkeeper integration
 - Fixed user tracking in overridden authenticate method
 
-## 1.0.1
+## 1.0.1 (2014-06-27)
 
 - Fixed `visitable` outside of requests
 
-## 1.0.0
+## 1.0.0 (2014-06-18)
 
 - Added support for any data store, and Mongoid out of the box
 - Added `track_visits_immediately` option
@@ -135,17 +210,17 @@ Breaking changes
 - Visits expire after inactivity, not fixed interval
 - Added `visit_duration` and `visitor_duration` options
 
-## 0.3.2
+## 0.3.2 (2014-06-15)
 
 - Fixed bot exclusion for visits
 - Fixed user method
 
-## 0.3.1
+## 0.3.1 (2014-06-12)
 
 - Fixed visitor cookies when set on server
 - Added `domain` option for server cookies
 
-## 0.3.0
+## 0.3.0 (2014-06-11)
 
 - Added `current_visit_token` and `current_visitor_token` method
 - Switched to UUIDs
@@ -153,47 +228,47 @@ Breaking changes
 - Skip server-side bot events
 - Added `request` argument to `exclude_method`
 
-## 0.2.2
+## 0.2.2 (2014-05-26)
 
 - Added `exclude_method` option
 - Added support for batch events
 - Fixed cookie encoding
 - Fixed `options` variable from being modified
 
-## 0.2.1
+## 0.2.1 (2014-05-16)
 
 - Fixed IE 8 error
 - Added `track_bots` option
 - Added `$authenticate` event
 
-## 0.2.0
+## 0.2.0 (2014-05-13)
 
 - Added event tracking (merged ahoy_events)
 - Added ahoy.js
 
-## 0.1.8
+## 0.1.8 (2014-05-11)
 
 - Fixed bug with `user_type` set to `false` instead of `nil`
 
-## 0.1.7
+## 0.1.7 (2014-05-11)
 
 - Made cookie functions public for ahoy_events
 
-## 0.1.6
+## 0.1.6 (2014-05-07)
 
 - Better user agent parser
 
-## 0.1.5
+## 0.1.5 (2014-05-01)
 
 - Added support for Doorkeeper
 - Added options to `visitable`
 - Added `landing_params` method
 
-## 0.1.4
+## 0.1.4 (2014-04-27)
 
 - Added `ahoy.ready()` and `ahoy.log()` for events
 
-## 0.1.3
+## 0.1.3 (2014-04-24)
 
 - Supports `current_user` from `ApplicationController`
 - Added `ahoy.reset()`
@@ -201,16 +276,16 @@ Breaking changes
 - Added experimental support for native apps
 - Prefer `ahoy` over `Ahoy`
 
-## 0.1.2
+## 0.1.2 (2014-04-15)
 
 - Attach user on Devise sign up
 - Ability to specify visit model
 
-## 0.1.1
+## 0.1.1 (2014-03-20)
 
 - Made most database columns optional
 - Performance hack for referer-parser
 
-## 0.1.0
+## 0.1.0 (2014-03-19)
 
 - First major release

data/CONTRIBUTING.md

@@ -2,17 +2,15 @@
 
 First, thanks for wanting to contribute. You’re awesome! :heart:
 
-## Questions
+## Help
 
-Use [Stack Overflow](https://stackoverflow.com/) with the tag `ahoy`.
+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/).
 
-## Feature Requests
+All features should be documented. If you don’t see a feature in the docs, assume it doesn’t exist.
 
-Create an issue. Start the title with `[Idea]`.
+## Bugs
 
-## Issues
-
-Think you’ve discovered an issue?
+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.
@@ -26,6 +24,10 @@ 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:

data/LICENSE.txt

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

data/README.md

@@ -1,15 +1,15 @@
 # Ahoy
 
-:fire: Simple, powerful analytics for Rails
+:fire: Simple, powerful, first-party 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.
 
-**Ahoy 2.0 was recently released!** See [how to upgrade](docs/Ahoy-2-Upgrade.md)
-
-: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)
+:postbox: Check out [Ahoy Email](https://github.com/ankane/ahoy_email) for emails and [Field Test](https://github.com/ankane/field_test) for A/B testing
 
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
+[![Build Status](https://github.com/ankane/ahoy/workflows/build/badge.svg?branch=master)](https://github.com/ankane/ahoy/actions)
+
 ## Installation
 
 Add this line to your application’s Gemfile:
@@ -31,12 +31,12 @@ Restart your web server, open a page in your browser, and a visit will be create
 Track your first event from a controller with:
 
 ```ruby
-ahoy.track "My first event", {language: "Ruby"}
+ahoy.track "My first event", language: "Ruby"
 ```
 
-### JavaScript & Native Apps
+### JavaScript, Native Apps, & AMP
 
-First, enable the API in `config/initializers/ahoy.rb`:
+Enable the API in `config/initializers/ahoy.rb`:
 
 ```ruby
 Ahoy.api = true
@@ -44,19 +44,43 @@ Ahoy.api = true
 
 And restart your web server.
 
-For JavaScript, add to `app/assets/javascripts/application.js`:
+### JavaScript
+
+For Rails 6 / Webpacker, run:
+
+```sh
+yarn add ahoy.js
+```
+
+And add to `app/javascript/packs/application.js`:
+
+```javascript
+import ahoy from "ahoy.js";
+```
+
+For Rails 5 / Sprockets, add to `app/assets/javascripts/application.js`:
 
 ```javascript
 //= require ahoy
 ```
 
-And track an event with:
+Track an event with:
 
 ```javascript
 ahoy.track("My second event", {language: "JavaScript"});
 ```
 
-For native apps, see the [API spec](#api-spec).
+### Native Apps
+
+Check out [Ahoy iOS](https://github.com/namolnad/ahoy-ios) and [Ahoy Android](https://github.com/instacart/ahoy-android).
+
+### GDPR Compliance
+
+Ahoy provides a number of options to help with GDPR compliance. See the [GDPR section](#gdpr-compliance-1) for more info.
+
+### Geocoding Setup
+
+To enable geocoding, see the [Geocoding section](#geocoding).
 
 ## How It Works
 
@@ -64,9 +88,9 @@ For native apps, see the [API spec](#api-spec).
 
 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
+- **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
 
 Use the `current_visit` method to access it.
@@ -77,33 +101,21 @@ Prevent certain Rails actions from creating visits with:
 skip_before_action :track_ahoy_visit
 ```
 
-This is typically useful for APIs.
-
-You can also defer visit tracking to JavaScript (Ahoy 1.0 behavior) with:
+This is typically useful for APIs. If your entire Rails app is an API, you can use:
 
 ```ruby
-Ahoy.server_side_visits = false
+Ahoy.api_only = true
 ```
 
-### Events
+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.
 
-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"});
+```ruby
+Ahoy.server_side_visits = :when_needed
 ```
 
-or track events automatically with:
-
-```javascript
-ahoy.trackAll();
-```
+### Events
 
-See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
+Each event has a `name` and `properties`. There are several ways to track events.
 
 #### Ruby
 
@@ -111,7 +123,7 @@ See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features
 ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
 ```
 
-or track actions automatically with:
+Track actions automatically with:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -120,51 +132,74 @@ class ApplicationController < ActionController::Base
   protected
 
   def track_action
-    ahoy.track "Viewed action", request.path_parameters
+    ahoy.track "Ran action", request.path_parameters
   end
 end
 ```
 
-#### Native Apps
+#### JavaScript
 
-See the [API spec](#api-spec).
+```javascript
+ahoy.track("Viewed book", {title: "The World is Flat"});
+```
 
-### Associated Models
+Track events automatically with:
 
-Say we want to associate orders with visits. Ahoy can do this automatically.
+```javascript
+ahoy.trackAll();
+```
 
-First, generate a migration and add a `visit_id` column (not needed for Mongoid).
+See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
 
-```ruby
-class AddVisitIdToOrders < ActiveRecord::Migration[5.1]
-  def change
-    add_column :orders, :visit_id, :bigint
-  end
-end
+#### Native Apps
+
+See the docs for [Ahoy iOS](https://github.com/namolnad/ahoy-ios) and [Ahoy Android](https://github.com/instacart/ahoy-android).
+
+#### AMP
+
+```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>
 ```
 
-Then, add `visitable` to the model.
+### Associated Models
+
+Say we want to associate orders with visits. Just add `visitable` to the model.
 
 ```ruby
 class Order < ApplicationRecord
-  visitable
+  visitable :ahoy_visit
 end
 ```
 
-When a visitor places an order, the `visit_id` column is automatically set :tada:
+When a visitor places an order, the `ahoy_visit_id` column is automatically set :tada:
 
 See where orders are coming from with simple joins:
 
 ```ruby
-Order.joins(:visit).group("referring_domain").count
-Order.joins(:visit).group("city").count
-Order.joins(:visit).group("device_type").count
+Order.joins(:ahoy_visit).group("referring_domain").count
+Order.joins(:ahoy_visit).group("city").count
+Order.joins(:ahoy_visit).group("device_type").count
+```
+
+Here’s what the migration to add the `ahoy_visit_id` column should look like:
+
+```ruby
+class AddVisitIdToOrders < ActiveRecord::Migration[6.0]
+  def change
+    add_column :orders, :ahoy_visit_id, :bigint
+  end
+end
 ```
 
-Customize the column and class name with:
+Customize the column with:
 
 ```ruby
-visitable :sign_up_visit, class_name: "Visit"
+visitable :sign_up_visit
 ```
 
 ### Users
@@ -205,7 +240,7 @@ or use a proc
 Ahoy.user_method = ->(controller) { controller.true_user }
 ```
 
-### Doorkeeper
+#### Doorkeeper
 
 To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
 
@@ -219,9 +254,31 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+#### Knock
+
+To attach the user with [Knock](https://github.com/nsarno/knock), either include `Knock::Authenticable`in `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Knock::Authenticable
+end
+```
+
+Or include it in Ahoy:
+
+```ruby
+Ahoy::BaseController.include Knock::Authenticable
+```
+
+And use:
+
+```ruby
+Ahoy.user_method = ->(controller) { controller.send(:authenticate_entity, "user") }
+```
+
 ### Exclusions
 
-Bots are excluded from tracking by default. To enable, use:
+Bots are excluded from tracking by default. To include them, use:
 
 ```ruby
 Ahoy.track_bots = true
@@ -243,7 +300,7 @@ By default, a new visit is created after 4 hours of inactivity. Change this with
 Ahoy.visit_duration = 30.minutes
 ```
 
-### Multiple Subdomains
+### Cookies
 
 To track visits across multiple subdomains, use:
 
@@ -251,20 +308,65 @@ To track visits across multiple subdomains, use:
 Ahoy.cookie_domain = :all
 ```
 
+Set other [cookie options](https://api.rubyonrails.org/classes/ActionDispatch/Cookies.html) with:
+
+```ruby
+Ahoy.cookie_options = {same_site: :lax}
+```
+
 ### Geocoding
 
-Disable geocoding with:
+Ahoy uses [Geocoder](https://github.com/alexreisner/geocoder) for geocoding. We recommend configuring [local geocoding](#local-geocoding) so IP addresses are not sent to a 3rd party service. If you do use a 3rd party service, be sure to add it to your GDPR subprocessor list. If Ahoy is configured to [mask ips](#ip-masking), the masked IP is used (this increases privacy but can reduce accuracy).
+
+To enable geocoding, update `config/initializers/ahoy.rb`:
 
 ```ruby
-Ahoy.geocode = false
+Ahoy.geocode = true
 ```
 
-Change the job queue with:
+Geocoding is performed in a background job so it doesn’t slow down web requests. The default job queue is `:ahoy`. Change this with:
 
 ```ruby
 Ahoy.job_queue = :low_priority
 ```
 
+### Local Geocoding
+
+For privacy and performance, we recommend geocoding locally. Add this line to your application’s Gemfile:
+
+```ruby
+gem 'maxminddb'
+```
+
+For city-level geocoding, download the [GeoLite2 City database](https://dev.maxmind.com/geoip/geoip2/geolite2/) and create `config/initializers/geocoder.rb` with:
+
+```ruby
+Geocoder.configure(
+  ip_lookup: :geoip2,
+  geoip2: {
+    file: "path/to/GeoLite2-City.mmdb"
+  }
+)
+```
+
+For country-level geocoding, install the `geoip-database` package. It’s preinstalled on Heroku. For Ubuntu, use:
+
+```sh
+sudo apt-get install geoip-database
+```
+
+And create `config/initializers/geocoder.rb` with:
+
+```ruby
+Geocoder.configure(
+  ip_lookup: :maxmind_local,
+  maxmind_local: {
+    file: "/usr/share/GeoIP/GeoIP.dat",
+    package: :country
+  }
+)
+```
+
 ### 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).
@@ -295,6 +397,94 @@ Exceptions are rescued so analytics do not break your app. Ahoy uses [Safely](ht
 Safely.report_exception_method = ->(e) { Rollbar.error(e) }
 ```
 
+## GDPR Compliance
+
+Ahoy provides a number of options to help with [GDPR compliance](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation).
+
+Update `config/initializers/ahoy.rb` with:
+
+```ruby
+class Ahoy::Store < Ahoy::DatabaseStore
+  def authenticate(data)
+    # disables automatic linking of visits and users
+  end
+end
+
+Ahoy.mask_ips = true
+Ahoy.cookies = false
+```
+
+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.mask_ips = true
+```
+
+IPs are masked before geolocation is performed.
+
+To mask previously collected IPs, use:
+
+```ruby
+Ahoy::Visit.find_each do |visit|
+  visit.update_column :ip, Ahoy.mask_ip(visit.ip)
+end
+```
+
+### Anonymity Sets & Cookies
+
+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
+Ahoy.cookies = false
+```
+
+Previously set cookies are automatically deleted.
+
+## Data Retention
+
+Data should only be retained for as long as it’s needed. Delete older data with:
+
+```ruby
+Ahoy::Visit.where("started_at < ?", 2.years.ago).find_in_batches do |visits|
+  visit_ids = visits.map(&:id)
+  Ahoy::Event.where(visit_id: visit_ids).delete_all
+  Ahoy::Visit.where(id: visit_ids).delete_all
+end
+```
+
+You can use [Rollup](https://github.com/ankane/rollup) to aggregate important data before you do.
+
+```ruby
+Ahoy::Visit.rollup("Visits", interval: "hour")
+```
+
+Delete data for a specific user with:
+
+```ruby
+user_id = 123
+visit_ids = Ahoy::Visit.where(user_id: user_id).pluck(:id)
+Ahoy::Event.where(visit_id: visit_ids).delete_all
+Ahoy::Visit.where(id: visit_ids).delete_all
+Ahoy::Event.where(user_id: user_id).delete_all
+```
+
 ## Development
 
 Ahoy is built with developers in mind. You can run the following code in your browser’s console.
@@ -369,6 +559,23 @@ end
 
 Two useful methods you can use are `request` and `controller`.
 
+You can pass additional visit data from JavaScript with:
+
+```javascript
+ahoy.configure({visitParams: {referral_code: 123}});
+```
+
+And use:
+
+```ruby
+class Ahoy::Store < Ahoy::DatabaseStore
+  def track_visit(data)
+    data[:referral_code] = request.parameters[:referral_code]
+    super(data)
+  end
+end
+```
+
 ### Use Different Models
 
 ```ruby
@@ -395,7 +602,7 @@ Ahoy::Visit.group(:country).count
 Ahoy::Visit.group(:referring_domain).count
 ```
 
-[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
+[Chartkick](https://www.chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
 
 ```erb
 <%= line_chart Ahoy::Visit.group_by_day(:started_at).count %>
@@ -403,7 +610,7 @@ Ahoy::Visit.group(:referring_domain).count
 
 ### Querying Events
 
-Ahoy provides two methods on the event model to make querying easier.
+Ahoy provides a few methods on the event model to make querying easier.
 
 To query on both name and properties, you can use:
 
@@ -414,9 +621,17 @@ Ahoy::Event.where_event("Viewed product", product_id: 123).count
 Or just query properties with:
 
 ```ruby
-Ahoy::Event.where_props(product_id: 123).count
+Ahoy::Event.where_props(product_id: 123, category: "Books").count
 ```
 
+Group by properties with:
+
+```ruby
+Ahoy::Event.group_prop(:product_id, :category).count
+```
+
+Note: MySQL and MariaDB always return string keys (include `"null"` for `nil`) for `group_prop`.
+
 ### Funnels
 
 It’s easy to create funnels.
@@ -429,6 +644,29 @@ viewed_checkout_ids = Ahoy::Event.where(user_id: added_item_ids, name: "Viewed c
 
 The same approach also works with visitor tokens.
 
+### Rollups
+
+Improve query performance by pre-aggregating data with [Rollup](https://github.com/ankane/rollup).
+
+```ruby
+Ahoy::Event.where(name: "Viewed store").rollup("Store views")
+```
+
+This is only needed if you have a lot of data.
+
+### Forecasting
+
+To forecast future visits and events, check out [Prophet](https://github.com/ankane/prophet).
+
+```ruby
+daily_visits = Ahoy::Visit.group_by_day(:started_at).count # uses Groupdate
+Prophet.forecast(daily_visits)
+```
+
+### Recommendations
+
+To make recommendations based on events, check out [Disco](https://github.com/ankane/disco#ahoy).
+
 ## Tutorials
 
 - [Tracking Metrics with Ahoy and Blazer](https://gorails.com/episodes/internal-metrics-with-ahoy-and-blazer)
@@ -437,7 +675,7 @@ The same approach also works with visitor tokens.
 
 ### Visits
 
-Generate visit and visitor tokens as [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier), and include these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
+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.
 
 Send a `POST` request to `/ahoy/visits` with `Content-Type: application/json` and a body like:
 
@@ -474,6 +712,65 @@ Send a `POST` request to `/ahoy/events` with `Content-Type: application/json` an
 }
 ```
 
+## Upgrading
+
+### 3.0
+
+If you installed Ahoy before 2.1 and want to keep legacy user agent parsing and bot detection, add to your Gemfile:
+
+```ruby
+gem "browser", "~> 2.0"
+gem "user_agent_parser"
+```
+
+And add to `config/initializers/ahoy.rb`:
+
+```ruby
+Ahoy.user_agent_parser = :legacy
+```
+
+### 2.2
+
+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
+Ahoy.bot_detection_version = 2
+```
+
+### 2.1
+
+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`:
+
+```ruby
+Ahoy.user_agent_parser = :device_detector
+```
+
+Backfill existing records with:
+
+```ruby
+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
+```
+
+### 2.0
+
+See the [upgrade guide](docs/Ahoy-2-Upgrade.md)
+
 ## History
 
 View the [changelog](https://github.com/ankane/ahoy/blob/master/CHANGELOG.md)
@@ -486,3 +783,20 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - Fix bugs and [submit pull requests](https://github.com/ankane/ahoy/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/ankane/ahoy.git
+cd ahoy
+bundle install
+bundle exec rake test
+```
+
+To test query methods, start PostgreSQL, MySQL, and MongoDB and use:
+
+```sh
+createdb ahoy_test
+mysqladmin create ahoy_test
+bundle exec rake test:query_methods
+```