AhoyCaptain

AhoyCaptain provides a mountable analytics dashboard with the following capabilities:

• Traffic Analysis: Top sources, top pages, landing pages, and exit pages.
• Segmentation: UTM reporting, top locations (country, region, city), and top devices (browser, OS, device type).
• Conversion Tracking: Goal tracking and funnels.
• Filtering: Filter data by Page, Location, Device type, OS, UTM tags, Goal, or Event Property.
• Data Export: CSV exports and date comparison functionality.

To install AhoyCaptain, add the gem to your bundle and run the generator. Note that this gem requires PostgreSQL and a JSONB column for your data.

1. Add the gem:

bundle add ahoy_captain

2. Run the installation generator:

rails g ahoy_captain:install

If your dataset exceeds 1GB, you should add indexes to improve performance. Run the following generator to create the necessary migration:

rails g ahoy_captain:migration

AhoyCaptain does not perform tracking itself; it provides a dashboard for data already being tracked by the ahoy gem.

By default, AhoyCaptain expects:

• A page view event named $view.
• controller and action properties within your Ahoy::Event objects.

You can customize these settings in config/initializers/ahoy_captain.rb.

To verify your events are set up correctly for the dashboard, run these commands in your Rails console:

# Check if page view events match the configured view name
AhoyCaptain.event.where(name: AhoyCaptain.config.event[:view_name]).count

# Check if events have route information
AhoyCaptain.event.with_routes.count

The event configuration object allows you to customize how event data is identified and queried. Default settings include:

• view_name: The property used to identify the view (default: "$view").
• url_column: The SQL expression used to construct the URL column.
• url_exists: The SQL expression used to check if the URL properties exist.

AhoyCaptain.configure do
  event.view_name = "custom_view"
  # Custom SQL for url_column or url_exists can be set here
end

AhoyCaptain uses an ActiveSupport::OrderedOptions object for cache configuration. By default, caching is disabled. You can enable it and specify the cache store and time-to-live (TTL).

AhoyCaptain.configure do
  cache.enabled = true
  cache.store = Rails.cache
  cache.ttl = 5.minutes
end

AhoyCaptain uses a configuration object to define how analytics events are mapped to database columns and names. The EventMethods module relies on AhoyCaptain.config.event to resolve column names and view identifiers.

Key configuration keys used by the internal logic include:

• event[:view_name]: The name of the event used to identify page views.
• event[:url_column]: The database column used to store the URL.
• event[:url_exists]: A condition used to filter events with valid routes.

Note: These settings directly affect the behavior of Ransack ransackers and scopes like page_view, with_url, and with_routes.

Use the following attributes to customize the dashboard appearance and behavior:

• view_name: The name of the view.
• theme: The UI theme (e.g., "dark").
• realtime_interval: How often the dashboard refreshes (default: 30.seconds).
• disabled_widgets: An array of widget identifiers that should not be rendered.

AhoyCaptain.configure do
  theme = "light"
  realtime_interval = 1.minute
  disabled_widgets = [:some_widget_id]
end

You can specify which Ahoy models to use for events and visits. The default values are ::Ahoy::Event and ::Ahoy::Visit.

AhoyCaptain.configure do
  models.event = "::MyCustomEvent"
  models.visit = "::MyCustomVisit"
end

AhoyCaptain extends Ahoy::Visit to allow Ransack filtering on the referring domain. It adds a virtual attribute ref_domain which uses an Arel SQL fragment to extract the domain name from the referring_domain column (stripping protocols and www.).

# The extension adds this ransacker to Ahoy::Visit
ransacker :ref_domain do
  Arel.sql("(substring(#{self.table_name}.referring_domain from '(?:.*://)?(?:www\.)?([^/?]*)'))")
end

Once filters are defined in an AhoyCaptain::FilterConfiguration::FilterCollection, you can interact with them using the following methods:

• filters: Returns the array of all registered Filter objects.
• [name]: Access a specific filter by its column name (e.g., collection[:status]).
• find(column): Returns the filter object matching the specified column (converted to a symbol).
• include?(name): Checks if a filter for the given column exists.
• delete(name): Removes a filter from the collection by its column name.
• each: Iterates over all filters in the collection.

You can extend the available time periods by using the add method. The range_proc argument must be a object that responds to .call and returns either a Range or an Array (typically representing the start and end times).

collection = AhoyCaptain::PeriodCollection.new

# Adding a custom 'last_week' period
collection.add(
  :last_week, 
  "Last Week", 
  -> { [1.week.ago, Time.current] }
)

collection.for(:last_week)
# => [1.week.ago, Time.current]