Ahoy Documentation

To comply with GDPR, you can mask IP addresses, disable cookies in favor of anonymity sets, and disable automatic linking of visits and users.

# config/initializers/ahoy.rb
class Ahoy::Store < Ahoy::DatabaseStore
  def authenticate(data)
    # disables automatic linking of visits and users
  end
end

Ahoy.mask_ips = true
Ahoy.cookies = :none

// Client-side JS
ahoy.configure({cookies: false});

For privacy and performance, use local geocoding via maxminddb (for city-level) or geoip (for country-level).

# City-level with MaxMind
# Gemfile: gem "maxminddb"
Geocoder.configure(
  ip_lookup: :geoip2,
  geoip2: {
    file: "path/to/GeoLite2-City.mmdb"
  }
)

# Country-level with GeoIP
# Gemfile: gem "geoip"
Geocoder.configure(
  ip_lookup: :maxmind_local,
  maxmind_local: {
    file: "/usr/share/GeoIP/GeoIP.dat",
    package: :country
  }
)

To comply with data retention policies, you can delete old visits and their associated events in batches. You can also use Rollup to aggregate data before deletion.

# Delete visits older than 2 years and their events
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

# Aggregate data before deleting
Ahoy::Visit.rollup("Visits", interval: "hour")

Use these commands in your browser console or Ruby environment to debug tracking behavior.

JavaScript (Browser Console):

• ahoy.reset(): Forces a new visit (reload the page after calling).
• ahoy.debug(): Enables logging.
• ahoy.debug(false): Disables logging.
• ahoy.configure({visitParams: {key: value}}): Passes additional data from JS to the visit.

Ruby:

• Ahoy.quiet = false: Enables debugging of API requests.

ahoy.reset(); // then reload the page
ahoy.debug();
ahoy.debug(false);
ahoy.configure({visitParams: {referral_code: 123}});

To allow tracking from JavaScript, native apps, or AMP, enable the API in your Ahoy initializer.

Ahoy.api = true

Install the ahoy.js package via your preferred package manager and import it in your application entry point.

bun add ahoy.js
# or
yarn add ahoy.js

// app/javascript/application.js
import ahoy from "ahoy.js"

To install Ahoy, add the ahoy_matey gem to your Gemfile and run the installation commands to generate the necessary files and migrations.

gem "ahoy_matey"

bundle install
rails generate ahoy:install
rails db:migrate

To remove all tracking data associated with a specific user ID, delete their events and visits, then delete any events explicitly tied to their user ID.

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