ahoy_matey 3.0.5 → 4.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17572400fdaab440040c753cf23084f2a47868e5c1ed12229e85fd1904e9c937
-  data.tar.gz: cc917af046906e308830fa1ffa9543db1bc1fe0f79488ccaddef090e6366433d
+  metadata.gz: fc5fc1f8ed102bd4a3fa7e78a5404c7d40b698d59cbbc644c5322e2bcb1b2e52
+  data.tar.gz: 7100ab100ed3a6ae66a4c4aa6b14c3c2e817c273ab677b7befbc6350fec5cff8
 SHA512:
-  metadata.gz: 325caa06934a20bf7a58f573fff7359b7058cf63e3e7576c48faf1bd5d08ac2564810a28e5a775c3ac324170754db4de35d46f43c0b421f8c4977760af19d153
-  data.tar.gz: e7af674522e09e3fb472b52546f30d10b743e2b2814efd97162d05cb1d4f9b13615dce211cd83e291da16e370a86cf7d8d384b16ad60d8af07c8ced8fbd17f59
+  metadata.gz: a41dd47317ab2932e0ddcc9231f3cca78887cdf2cf98ca3506cb0ccd8f1f70ed050dafe8e17e764224fe29018ba5cb35afab5068059338f63e832298d98547cd
+  data.tar.gz: f170800b1f7490aec5be31dab5e59f5824ab0a261ceb4fac9b5a1ad31fd8525c7f424c3f2080c8e75f9564763a69c9c6a56a854c848d1453cc3299b5f5c822f0

data/CHANGELOG.md

@@ -1,3 +1,59 @@
+## 4.2.1 (2023-02-23)
+
+- Updated Ahoy.js to 0.4.2
+
+## 4.2.0 (2023-02-07)
+
+- Added primary key type to generated migration
+- Updated Ahoy.js to 0.4.1
+
+## 4.1.0 (2022-06-12)
+
+- Ensure `exclude_method` is only called once per request
+- Fixed error with Mongoid when `Mongoid.raise_not_found_error` is `true`
+- Fixed association for Mongoid
+
+## 4.0.3 (2022-01-15)
+
+- Support for `importmap-rails` is no longer experimental
+- Fixed asset precompilation error with `importmap-rails`
+
+## 4.0.2 (2021-11-06)
+
+- Added experimental support for `importmap-rails`
+
+## 4.0.1 (2021-08-18)
+
+- Added support for `where_event`, `where_props`, and `where_group` for SQLite
+- Fixed results with `where_event` for MySQL, MariaDB, and Postgres `hstore`
+- Fixed results with `where_props` and `where_group` when used with other scopes for MySQL, MariaDB, and Postgres `hstore`
+
+## 4.0.0 (2021-08-14)
+
+- Disabled geocoding by default (this was already the case for new installations with 3.2.0+)
+- Made the `geocoder` gem an optional dependency
+- Updated Ahoy.js to 0.4.0
+- Updated API to return 400 status code when missing required parameters
+- Dropped support for Ruby < 2.6 and Rails < 5.2
+
+## 3.3.0 (2021-08-13)
+
+- Added `country_code` to geocoding
+- Updated Ahoy.js to 0.3.9
+- Fixed install generator for MariaDB
+
+## 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

data/LICENSE.txt

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

data/README.md

@@ -2,20 +2,20 @@
 
 :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.
+Track visits and events in Ruby, JavaScript, and native apps. Data is stored in your database by default, and you can customize it for any data store as you grow.
 
 :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://travis-ci.org/ankane/ahoy.svg?branch=master)](https://travis-ci.org/ankane/ahoy)
+[![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:
 
 ```ruby
-gem 'ahoy_matey'
+gem "ahoy_matey"
 ```
 
 And run:
@@ -46,6 +46,18 @@ And restart your web server.
 
 ### JavaScript
 
+For Rails 7 / Importmap, add to `config/importmap.rb`:
+
+```ruby
+pin "ahoy", to: "ahoy.js"
+```
+
+And add to `app/javascript/application.js`:
+
+```javascript
+import "ahoy"
+```
+
 For Rails 6 / Webpacker, run:
 
 ```sh
@@ -55,7 +67,7 @@ yarn add ahoy.js
 And add to `app/javascript/packs/application.js`:
 
 ```javascript
-import ahoy from "ahoy.js";
+import ahoy from "ahoy.js"
 ```
 
 For Rails 5 / Sprockets, add to `app/assets/javascripts/application.js`:
@@ -70,6 +82,14 @@ Track an event with:
 ahoy.track("My second event", {language: "JavaScript"});
 ```
 
+### Native Apps
+
+Check out [Ahoy iOS](https://github.com/namolnad/ahoy-ios) and [Ahoy Android](https://github.com/instacart/ahoy-android).
+
+### Geocoding Setup
+
+To enable geocoding, see the [Geocoding section](#geocoding).
+
 ### GDPR Compliance
 
 Ahoy provides a number of options to help with GDPR compliance. See the [GDPR section](#gdpr-compliance-1) for more info.
@@ -135,17 +155,11 @@ end
 ahoy.track("Viewed book", {title: "The World is Flat"});
 ```
 
-Track events automatically with:
-
-```javascript
-ahoy.trackAll();
-```
-
 See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features.
 
 #### Native Apps
 
-For Android, check out [Ahoy Android](https://github.com/instacart/ahoy-android). For other platforms, see the [API spec](#api-spec).
+See the docs for [Ahoy iOS](https://github.com/namolnad/ahoy-ios) and [Ahoy Android](https://github.com/instacart/ahoy-android).
 
 #### AMP
 
@@ -181,9 +195,9 @@ 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]
+class AddAhoyVisitToOrders < ActiveRecord::Migration[7.0]
   def change
-    add_column :orders, :ahoy_visit_id, :bigint
+    add_reference :orders, :ahoy_visit
   end
 end
 ```
@@ -196,7 +210,7 @@ visitable :sign_up_visit
 
 ### Users
 
-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.
+Ahoy automatically attaches the `current_user` to the visit. With [Devise](https://github.com/plataformatec/devise), it attaches the user even if they sign in after the visit starts.
 
 With other authentication frameworks, add this to the end of your sign in method:
 
@@ -306,71 +320,118 @@ Set other [cookie options](https://api.rubyonrails.org/classes/ActionDispatch/Co
 Ahoy.cookie_options = {same_site: :lax}
 ```
 
-### Geocoding
+You can also [disable cookies](#anonymity-sets--cookies)
 
-Disable geocoding 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
-Ahoy.geocode = false
+Ahoy.token_generator = -> { Druuid.gen }
 ```
 
-The default job queue is `:ahoy`. Change this with:
+### Throttling
+
+You can use [Rack::Attack](https://github.com/kickstarter/rack-attack) to throttle requests to the API.
 
 ```ruby
-Ahoy.job_queue = :low_priority
+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 Performance
+### Exceptions
 
-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.
+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:
 
-Add this line to your application’s Gemfile:
+```ruby
+Safely.report_exception_method = ->(e) { Rollbar.error(e) }
+```
+
+## Geocoding
+
+Ahoy uses [Geocoder](https://github.com/alexreisner/geocoder) for geocoding. We recommend configuring [local geocoding](#local-geocoding) or [load balancer geocoding](#load-balancer-geocoding) so IP addresses are not sent to a 3rd party service. If you do use a 3rd party service and adhere to GDPR, be sure to add it to your subprocessor list. If Ahoy is configured to [mask IPs](#ip-masking), the masked IP is used (this can reduce accuracy but is better for privacy).
+
+To enable geocoding, add this line to your application’s Gemfile:
+
+```ruby
+gem "geocoder"
+```
+
+And update `config/initializers/ahoy.rb`:
 
 ```ruby
-gem 'maxminddb'
+Ahoy.geocode = true
 ```
 
-And create an initializer at `config/initializers/geocoder.rb` 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: Rails.root.join("lib", "GeoLite2-City.mmdb")
+    file: "path/to/GeoLite2-City.mmdb"
   }
 )
 ```
 
-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.
+For country-level geocoding, install the `geoip-database` package. It’s preinstalled on Heroku. For Ubuntu, use:
 
-### Token Generation
+```sh
+sudo apt-get install geoip-database
+```
 
-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).
+And create `config/initializers/geocoder.rb` with:
 
 ```ruby
-Ahoy.token_generator = -> { Druuid.gen }
+Geocoder.configure(
+  ip_lookup: :maxmind_local,
+  maxmind_local: {
+    file: "/usr/share/GeoIP/GeoIP.dat",
+    package: :country
+  }
+)
 ```
 
-### Throttling
-
-You can use [Rack::Attack](https://github.com/kickstarter/rack-attack) to throttle requests to the API.
+### Load Balancer Geocoding
 
-```ruby
-class Rack::Attack
-  throttle("ahoy/ip", limit: 20, period: 1.minute) do |req|
-    if req.path.start_with?("/ahoy/")
-      req.ip
-    end
-  end
-end
-```
+Some load balancers can add geocoding information to request headers.
 
-### Exceptions
+- [nginx](https://nginx.org/en/docs/http/ngx_http_geoip_module.html)
+- [Google Cloud](https://cloud.google.com/load-balancing/docs/custom-headers)
+- [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/200168236-Configuring-Cloudflare-IP-Geolocation)
 
-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:
+Update `config/initializers/ahoy.rb` with:
 
 ```ruby
-Safely.report_exception_method = ->(e) { Rollbar.error(e) }
+Ahoy.geocode = false
+
+class Ahoy::Store < Ahoy::DatabaseStore
+  def track_visit(data)
+    data[:country] = request.headers["<country-header>"]
+    data[:region] = request.headers["<region-header>"]
+    data[:city] = request.headers["<city-header>"]
+    super(data)
+  end
+end
 ```
 
 ## GDPR Compliance
@@ -431,7 +492,13 @@ Ahoy can switch from cookies to [anonymity sets](https://privacypatterns.org/pat
 Ahoy.cookies = false
 ```
 
-Previously set cookies are automatically deleted.
+Previously set cookies are automatically deleted. If you use JavaScript tracking, also set:
+
+```javascript
+ahoy.configure({cookies: false});
+```
+
+Note: With anonymity sets, visits no longer expire after 4 hours of inactivity. A new visit is only created when the IP mask or user agent changes (for instance, when a user updates their browser). There are plans to address this in the next major version.
 
 ## Data Retention
 
@@ -606,7 +673,7 @@ Group by properties with:
 Ahoy::Event.group_prop(:product_id, :category).count
 ```
 
-Note: MySQL and MariaDB always return string keys (include `"null"` for `nil`) for `group_prop`.
+Note: MySQL and MariaDB always return string keys (including `"null"` for `nil`) for `group_prop`.
 
 ### Funnels
 
@@ -639,6 +706,24 @@ daily_visits = Ahoy::Visit.group_by_day(:started_at).count # uses Groupdate
 Prophet.forecast(daily_visits)
 ```
 
+### Anomaly Detection
+
+To detect anomalies in visits and events, check out [AnomalyDetection.rb](https://github.com/ankane/AnomalyDetection.rb).
+
+```ruby
+daily_visits = Ahoy::Visit.group_by_day(:started_at).count # uses Groupdate
+AnomalyDetection.detect(daily_visits, period: 7)
+```
+
+### Breakout Detection
+
+To detect breakouts in visits and events, check out [Breakout](https://github.com/ankane/breakout).
+
+```ruby
+daily_visits = Ahoy::Visit.group_by_day(:started_at).count # uses Groupdate
+Breakout.detect(daily_visits)
+```
+
 ### Recommendations
 
 To make recommendations based on events, check out [Disco](https://github.com/ankane/disco#ahoy).
@@ -690,62 +775,19 @@ 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
-```
+### 4.0
 
-### 2.2
+There are two notable changes to geocoding:
 
-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`:
+1. Geocoding is now disabled by default (this was already the case for new installations with 3.2.0+). Check out the instructions for [how to enable it](#geocoding).
 
-```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. The `geocoder` gem is now an optional dependency. To use geocoding, add it to your Gemfile:
 
-### 2.0
+  ```ruby
+  gem "geocoder"
+  ```
 
-See the [upgrade guide](docs/Ahoy-2-Upgrade.md)
+Also, check out the [upgrade notes](https://github.com/ankane/ahoy.js#upgrading) for Ahoy.js.
 
 ## History
 
@@ -769,10 +811,10 @@ bundle install
 bundle exec rake test
 ```
 
-To test query methods, start PostgreSQL, MySQL, and MongoDB and use:
+To test different adapters, use:
 
 ```sh
-createdb ahoy_test
-mysqladmin create ahoy_test
-bundle exec rake test:query_methods
+ADAPTER=postgresql bundle exec rake test
+ADAPTER=mysql2 bundle exec rake test
+ADAPTER=mongoid bundle exec rake test
 ```

data/app/controllers/ahoy/base_controller.rb

@@ -5,19 +5,27 @@ module Ahoy
     skip_after_action(*filters, raise: false)
     skip_around_action(*filters, raise: false)
 
-    before_action :verify_request_size
-    before_action :renew_cookies
-
     if respond_to?(:protect_from_forgery)
       protect_from_forgery with: :null_session, if: -> { Ahoy.protect_from_forgery }
     end
 
+    before_action :verify_request_size
+    before_action :check_params
+    before_action :renew_cookies
+
     protected
 
     def ahoy
       @ahoy ||= Ahoy::Tracker.new(controller: self, api: true)
     end
 
+    def check_params
+      if ahoy.send(:missing_params?)
+        logger.info "[ahoy] Missing required parameters"
+        render plain: "Missing required parameters\n", status: :bad_request
+      end
+    end
+
     # set proper ttl if cookie generated from JavaScript
     # approach is not perfect, as user must reload the page
     # for new cookie settings to take effect
@@ -28,7 +36,7 @@ module Ahoy
     def verify_request_size
       if request.content_length > Ahoy.max_content_length
         logger.info "[ahoy] Payload too large"
-        render plain: "Payload too large\n", status: 413
+        render plain: "Payload too large\n", status: :payload_too_large
       end
     end
   end

data/app/jobs/ahoy/geocode_job.rb

@@ -1,4 +1,5 @@
 # for smooth update from Ahoy 1 -> 2
+# TODO remove in 5.0
 module Ahoy
   class GeocodeJob < ActiveJob::Base
     queue_as { Ahoy.job_queue }

data/app/jobs/ahoy/geocode_v2_job.rb

@@ -6,6 +6,8 @@ module Ahoy
       location =
         begin
           Geocoder.search(ip).first
+        rescue NameError
+          raise "Add the geocoder gem to your Gemfile to use geocoding"
         rescue => e
           Ahoy.log "Geocode error: #{e.class.name}: #{e.message}"
           nil
@@ -14,6 +16,7 @@ module Ahoy
       if location && location.country.present?
         data = {
           country: location.country,
+          country_code: location.try(:country_code).presence,
           region: location.try(:state).presence,
           city: location.try(:city).presence,
           postal_code: location.try(:postal_code).presence,

data/lib/ahoy/base_store.rb

@@ -24,7 +24,11 @@ module Ahoy
     def user
       @user ||= begin
         if Ahoy.user_method.respond_to?(:call)
-          Ahoy.user_method.call(controller)
+          if Ahoy.user_method.arity == 1
+            Ahoy.user_method.call(controller)
+          else
+            Ahoy.user_method.call(controller, request)
+          end
         else
           controller.send(Ahoy.user_method) if controller.respond_to?(Ahoy.user_method, true)
         end

data/lib/ahoy/controller.rb

@@ -39,12 +39,12 @@ module Ahoy
     end
 
     def set_ahoy_request_store
-      previous_value = Thread.current[:ahoy]
+      previous_value = Ahoy.instance
       begin
-        Thread.current[:ahoy] = ahoy
+        Ahoy.instance = ahoy
         yield
       ensure
-        Thread.current[:ahoy] = previous_value
+        Ahoy.instance = previous_value
       end
     end
   end

data/lib/ahoy/database_store.rb

@@ -53,7 +53,12 @@ module Ahoy
 
     def visit
       unless defined?(@visit)
-        @visit = visit_model.where(visit_token: ahoy.visit_token).first if ahoy.visit_token
+        if defined?(Mongoid::Document) && visit_model < Mongoid::Document
+          # find_by raises error by default when not found
+          @visit = visit_model.where(visit_token: ahoy.visit_token).first if ahoy.visit_token
+        else
+          @visit = visit_model.find_by(visit_token: ahoy.visit_token) if ahoy.visit_token
+        end
       end
       @visit
     end

data/lib/ahoy/engine.rb

@@ -26,5 +26,12 @@ module Ahoy
         alias_method :call, :call_with_quiet_ahoy
       end
     end
+
+    # for importmap
+    initializer "ahoy.importmap" do |app|
+      if defined?(Importmap)
+        app.config.assets.precompile << "ahoy.js"
+      end
+    end
   end
 end

data/lib/ahoy/model.rb

@@ -7,7 +7,7 @@ module Ahoy
       end
       class_eval %{
         def set_ahoy_visit
-          self.#{name} ||= Thread.current[:ahoy].try(:visit_or_create)
+          self.#{name} ||= Ahoy.instance.try(:visit_or_create)
         end
       }
     end