ahoy_analytics 0.1.0

data/app/models/ahoy_analytics/live_stats.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module AhoyAnalytics
+  class LiveStats
+    LIVE_WINDOW = 5.minutes
+
+    def self.build(now: Time.zone.now)
+      new(now).build
+    end
+
+    def initialize(now)
+      @now = now
+    end
+
+    def build
+      today_range = today
+      yesterday_range = yesterday
+
+      current_visitors = Ahoy::Visit.live_visitors_count
+
+      today_sessions = Ahoy::Visit.where(started_at: today_range).count
+      yesterday_sessions = Ahoy::Visit.where(started_at: yesterday_range).count
+
+      today_visitors = Ahoy::Visit.where(started_at: today_range).distinct.count(:visitor_token)
+      yesterday_visitors = Ahoy::Visit.where(started_at: yesterday_range).distinct.count(:visitor_token)
+
+      today_pageviews = Ahoy::Event.where(name: "pageview", time: today_range).count
+      yesterday_pageviews = Ahoy::Event.where(name: "pageview", time: yesterday_range).count
+
+      buckets = 1.hour
+      session_spark = Ahoy::Visit.sparkline_today_vs_yesterday(bucket: buckets, now: now, yesterday_full_day: true)
+      pageview_spark = sparkline_events_today_vs_yesterday(bucket: buckets, now: now, yesterday_full_day: true)
+
+      {
+        currentVisitors: current_visitors,
+        todayVisitors: {
+          count: today_visitors,
+          change: pct_change(yesterday_visitors, today_visitors)
+        },
+        todaySessions: {
+          count: today_sessions,
+          change: pct_change(yesterday_sessions, today_sessions),
+          sparkline: session_spark
+        },
+        todayPageviews: {
+          count: today_pageviews,
+          change: pct_change(yesterday_pageviews, today_pageviews),
+          sparkline: pageview_spark
+        },
+        sessionsByLocation: sessions_by_location(today_range),
+        visitorDots: visitor_dots
+      }
+    end
+
+    private
+
+      attr_reader :now
+
+      def today
+        now.beginning_of_day..now
+      end
+
+      def yesterday
+        (today.begin - 1.day)..today.begin
+      end
+
+      def sessions_by_location(range)
+        Ahoy::Visit
+          .where(started_at: range)
+          .group(:country, :region, :city)
+          .order(Arel.sql("COUNT(*) DESC"))
+          .limit(5)
+          .count
+          .map do |(country, region, city), count|
+            {
+              country: country.to_s,
+              region: region.to_s.presence,
+              city: city.to_s.presence,
+              countryCode: country.to_s,
+              visitors: count
+            }
+          end
+      end
+
+      def visitor_dots
+        Ahoy::Visit.live_dots(limit: 200, window: LIVE_WINDOW, now: now).sort_by { |dot| -dot[:ts].to_i }
+      end
+
+      def sparkline_events_today_vs_yesterday(bucket:, now:, yesterday_full_day: true)
+        current_time = now || Time.zone.now
+        start_today = current_time.beginning_of_day
+        bucket_seconds = bucket.to_i
+        bucket_count_today = (((current_time - start_today) / bucket).floor + 1)
+          .clamp(1, 24 * 60 * 60 / bucket_seconds)
+        full_day_buckets = (24 * 60 * 60) / bucket_seconds
+        bucket_count_yday = yesterday_full_day ? full_day_buckets : bucket_count_today
+
+        today_series = event_series_counts(
+          start_at: start_today,
+          buckets: bucket_count_today,
+          bucket_seconds: bucket_seconds
+        )
+
+        yesterday_series = event_series_counts(
+          start_at: start_today - 1.day,
+          buckets: bucket_count_yday,
+          bucket_seconds: bucket_seconds
+        )
+
+        { today: today_series, yesterday: yesterday_series }
+      end
+
+      def event_series_counts(start_at:, buckets:, bucket_seconds:)
+        finish = start_at + (buckets - 1) * bucket_seconds
+        sec = bucket_seconds.to_i
+        sec = 1 if sec <= 0
+        sec = 86_400 if sec > 86_400
+        start_ts = ActiveRecord::Base.connection.quote("#{start_at.utc.strftime('%Y-%m-%d %H:%M:%S')}+00")
+        finish_ts = ActiveRecord::Base.connection.quote("#{finish.utc.strftime('%Y-%m-%d %H:%M:%S')}+00")
+        sql = <<~SQL.squish
+          WITH series AS (
+            SELECT generate_series(
+              TIMESTAMPTZ #{start_ts},
+              TIMESTAMPTZ #{finish_ts},
+              INTERVAL '#{sec} seconds'
+            ) AS bucket
+          )
+          SELECT
+            s.bucket AS bucket,
+            COUNT(e.id) AS value
+          FROM series s
+          LEFT JOIN ahoy_events e
+            ON e.time >= s.bucket
+           AND e.time < s.bucket + INTERVAL '#{sec} seconds'
+           AND e.name = 'pageview'
+          GROUP BY s.bucket
+          ORDER BY s.bucket ASC
+        SQL
+
+        rows = ActiveRecord::Base.connection.exec_query(sql)
+        rows.rows.map { |(_, value)| value.to_i }
+      end
+
+      def pct_change(previous, current)
+        previous = previous.to_f
+        current = current.to_f
+        return 0 if previous <= 0
+
+        (((current - previous) / previous) * 100).round
+      end
+  end
+end

data/app/models/ahoy_analytics/setting.rb

@@ -0,0 +1,19 @@
+module AhoyAnalytics
+  class Setting < ApplicationRecord
+    self.table_name = "analytics_settings"
+
+    validates :key, presence: true, uniqueness: true
+
+    def self.get_bool(key, fallback: false)
+      rec = find_by(key: key)
+      return fallback if rec.nil?
+      ActiveModel::Type::Boolean.new.cast(rec.value)
+    end
+
+    def self.set_bool(key, value)
+      rec = find_or_initialize_by(key: key)
+      rec.value = ActiveModel::Type::Boolean.new.cast(value) ? "true" : "false"
+      rec.save!
+    end
+  end
+end

data/app/models/analytics/source_catalog.rb

@@ -0,0 +1,48 @@
+module Analytics
+  module SourceCatalog
+    SOURCE_MAP = {
+      "Gmail" => /(^|\.)mail\.google\.com$|(^|\.)gmail\./i,
+      "Outlook.com" => /(^|\.)outlook\.|(^|\.)live\.|(^|\.)office\.com/i,
+      "Yahoo! Mail" => /(^|\.)mail\.yahoo\./i,
+      "Proton Mail" => /(^|\.)mail\.proton\.me$/i,
+      "iCloud Mail" => /(^|\.)mail\.icloud\.com$/i,
+      "Google" => /(^|\.)google\./i,
+      "Bing" => /(^|\.)bing\./i,
+      "DuckDuckGo" => /duckduckgo/i,
+      "Yahoo!" => /(^|\.)yahoo\./i,
+      "Baidu" => /(^|\.)baidu\./i,
+      "Yandex" => /(^|\.)yandex\./i,
+      "Ecosia" => /(^|\.)ecosia\./i,
+      "Qwant" => /(^|\.)qwant\./i,
+      "Brave" => /(^|\.)search\.brave\./i,
+      "AOL" => /(^|\.)aol\./i,
+      "Ask" => /(^|\.)ask\./i,
+      "Naver" => /(^|\.)naver\./i,
+      "Seznam" => /(^|\.)seznam\./i,
+      "Sogou" => /(^|\.)sogou\./i,
+      "Startpage" => /(^|\.)startpage\./i,
+      "Perplexity" => /(^|\.)perplexity\./i,
+      "ChatGPT" => /(^|\.)chatgpt\./i,
+      "Facebook" => /(^|\.)facebook\./i,
+      "Instagram" => /(^|\.)instagram\./i,
+      "Twitter" => /(^|\.)twitter\.|(^|\.)x\.com/i,
+      "LinkedIn" => /(^|\.)linkedin\./i,
+      "Pinterest" => /(^|\.)pinterest\./i,
+      "Reddit" => /(^|\.)reddit\./i,
+      "YouTube" => /(^|\.)youtube\.|(^|\.)youtu\.be/i,
+      "TikTok" => /(^|\.)tiktok\./i,
+      "WhatsApp" => /(^|\.)whatsapp\./i,
+      "Telegram" => /(^|\.)telegram\./i,
+      "Snapchat" => /(^|\.)snapchat\./i,
+      "Threads" => /(^|\.)threads\.net/i,
+      "Discord" => /(^|\.)discord\./i,
+      "Quora" => /(^|\.)quora\./i,
+      "VK" => /(^|\.)vk\.com/i,
+      "Weibo" => /(^|\.)weibo\./i,
+      "GitHub" => /(^|\.)github\./i,
+      "StackOverflow" => /(^|\.)stackoverflow\./i,
+      "Stack Overflow" => /(^|\.)stackoverflow\./i,
+      "Hacker News" => /(^|\.)news\.ycombinator\.com$/i
+    }.freeze
+  end
+end

data/app/views/layouts/ahoy_analytics/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Analytics</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= inertia_ssr_head %>
+    <%= ahoy_analytics_head_tags("analytics-ui") %>
+  </head>
+  <body class="min-h-dvh bg-background text-foreground">
+    <%= ahoy_analytics_window_config_tag %>
+    <%= yield %>
+    <%= ahoy_analytics_body_tags("analytics-ui") %>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,21 @@
+AhoyAnalytics::Engine.routes.draw do
+  root to: "analytics#show"
+  get "/live", to: "live#show", as: :live
+  get "/_/referrers/:source", to: "analytics#show", as: :referrers_dialog
+  get "/_/:dialog", to: "analytics#show", as: :dialog
+
+  resource :top_stats, only: [ :show ]
+  resource :main_graph, only: [ :show ], controller: "main_graph"
+  resources :sources, only: [ :index ]
+  resources :search_terms, only: [ :index ]
+  resources :referrers, only: [ :index ]
+  resources :pages, only: [ :index ]
+  resources :locations, only: [ :index ]
+  resources :devices, only: [ :index ]
+  resources :behaviors, only: [ :index ]
+  resource :export, only: [ :show ]
+
+  get "/assets/*path", to: "assets#show", as: :engine_asset
+  get "/build/*path", to: "assets#show", as: :engine_build_asset
+  get "/images/*path", to: "assets#show", as: :engine_image_asset
+end

data/config/vite.json

@@ -0,0 +1,22 @@
+{
+  "all": {
+    "sourceCodeDir": "app/frontend",
+    "entrypointsDir": "entrypoints",
+    "publicDir": "app/assets/ahoy_analytics",
+    "publicOutputDir": "build",
+    "base": "/admin/analytics",
+    "watchAdditionalPaths": []
+  },
+  "development": {
+    "autoBuild": true,
+    "port": 3038
+  },
+  "test": {
+    "autoBuild": true,
+    "publicOutputDir": "build-test",
+    "port": 3039
+  },
+  "production": {
+    "ssrBuildEnabled": false
+  }
+}

data/db/migrate/20251006104056_create_ahoy_visits_and_events.rb

@@ -0,0 +1,62 @@
+class CreateAhoyVisitsAndEvents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :ahoy_visits do |t|
+      t.string :visit_token
+      t.string :visitor_token
+
+      # the rest are recommended but optional
+      # simply remove any you don't want
+
+      # user
+      t.references :user
+
+      # standard
+      t.string :ip
+      t.text :user_agent
+      t.text :referrer
+      t.string :referring_domain
+      t.text :landing_page
+
+      # technology
+      t.string :browser
+      t.string :os
+      t.string :device_type
+
+      # location
+      t.string :country
+      t.string :region
+      t.string :city
+      t.float :latitude
+      t.float :longitude
+
+      # utm parameters
+      t.string :utm_source
+      t.string :utm_medium
+      t.string :utm_term
+      t.string :utm_content
+      t.string :utm_campaign
+
+      # native apps
+      t.string :app_version
+      t.string :os_version
+      t.string :platform
+
+      t.datetime :started_at
+    end
+
+    add_index :ahoy_visits, :visit_token, unique: true
+    add_index :ahoy_visits, [ :visitor_token, :started_at ]
+
+    create_table :ahoy_events do |t|
+      t.references :visit
+      t.references :user
+
+      t.string :name
+      t.jsonb :properties
+      t.datetime :time
+    end
+
+    add_index :ahoy_events, [ :name, :time ]
+    add_index :ahoy_events, :properties, using: :gin, opclass: :jsonb_path_ops
+  end
+end

data/db/migrate/20251006105012_add_analytics_fields_to_ahoy_visits.rb

@@ -0,0 +1,11 @@
+class AddAnalyticsFieldsToAhoyVisits < ActiveRecord::Migration[8.1]
+  def change
+    change_table :ahoy_visits, bulk: true do |t|
+      t.string  :screen_size
+      t.string  :browser_version
+      t.string  :hostname
+    end
+
+    add_index :ahoy_visits, :started_at unless index_exists?(:ahoy_visits, :started_at)
+  end
+end

data/db/migrate/20251012090000_create_analytics_funnels_and_imports.rb

@@ -0,0 +1,52 @@
+class CreateAnalyticsFunnelsAndImports < ActiveRecord::Migration[8.1]
+  def change
+    create_table :analytics_funnels do |t|
+      t.string  :name, null: false
+      t.jsonb   :steps, null: false, default: []
+      t.integer :created_by_id
+      t.timestamps
+    end
+
+    add_index :analytics_funnels, :name, unique: true
+
+    create_table :analytics_settings do |t|
+      t.string :key, null: false
+      t.text   :value
+      t.timestamps
+    end
+    add_index :analytics_settings, :key, unique: true
+
+    # Imported aggregates for optional GA/CSV imports. Minimal columns to support Pages/Entry/Exit parity
+    create_table :imported_pages do |t|
+      t.date   :date, null: false
+      t.text   :page, null: false
+      t.integer :visitors, default: 0, null: false
+      t.integer :pageviews, default: 0, null: false
+      t.integer :bounces, default: 0, null: false
+      t.bigint  :total_time_on_page, default: 0, null: false # seconds
+      t.bigint  :total_time_on_page_visits, default: 0, null: false
+    end
+    add_index :imported_pages, [ :date, :page ]
+
+    create_table :imported_entry_pages do |t|
+      t.date   :date, null: false
+      t.text   :entry_page, null: false
+      t.integer :visitors, default: 0, null: false
+      t.integer :entrances, default: 0, null: false
+      t.integer :bounces, default: 0, null: false
+      t.integer :visit_duration, default: 0, null: false # average seconds rounded
+    end
+    add_index :imported_entry_pages, [ :date, :entry_page ]
+
+    create_table :imported_exit_pages do |t|
+      t.date   :date, null: false
+      t.text   :exit_page, null: false
+      t.integer :visitors, default: 0, null: false
+      t.integer :exits, default: 0, null: false
+      t.integer :pageviews, default: 0, null: false
+      t.integer :bounces, default: 0, null: false
+      t.integer :visit_duration, default: 0, null: false # average seconds rounded
+    end
+    add_index :imported_exit_pages, [ :date, :exit_page ]
+  end
+end

data/db/migrate/20251013021500_add_analytics_indexes.rb

@@ -0,0 +1,14 @@
+class AddAnalyticsIndexes < ActiveRecord::Migration[8.1]
+  def change
+    # Accelerate equality lookups on page path stored in event properties
+    add_index :ahoy_events,
+              "LOWER((properties->>'page'))",
+              name: "index_ahoy_events_on_lower_page"
+
+    # Speed up live map queries that require coordinates
+    add_index :ahoy_visits,
+              [ :latitude, :longitude ],
+              where: "latitude IS NOT NULL AND longitude IS NOT NULL",
+              name: "index_ahoy_visits_on_coordinates"
+  end
+end