analytic 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb82e829dff15357a11068a257ee1fb1ff2c4257de41703580a8f320ffee669a
-  data.tar.gz: 7e1bb82f6cec5b2fa12089fb7fbd3dfed87690da645eb3746ca22017de640f82
+  metadata.gz: e283c032e4bc20c3b16244bee1b0a4b65e236626bdd9d75c05ef44116c6aa679
+  data.tar.gz: 8f9e592c750579ed57665364b2b9f0fd5c7cf6455e68e134e1b7817eda7c2713
 SHA512:
-  metadata.gz: 717be1d6814479751169f69fbdb39bb2413f023a001f0ea9033dbae146fd84357014ba67f3da150f77ac96d44500f45d5cfda0963e8cba428bd876e637e8e678
-  data.tar.gz: 56c3f9f5f29ee9a6564eca830cf9c895290f0eec4d97f179c9d031acb919ad1ff799018ee557c98a75252c28eec9da70ae445ee165e3ba267ec70b4f94761609
+  metadata.gz: b88a20a9fcdebaa18d0702a0dc22ceaf02cf88d383d0f4d3de59558c6073b0d1b85993cc49ef1a19d39d98fed32c321aa82241df42a32440e7bdb8138eab4af6
+  data.tar.gz: 9c61764e8b904c336551099e1155c4bcfdcda88f32cd622bb7f38d57adc157bfd8c9a1583cbb9e09e7866a1103c127758239efd0431e00dd4b5aca25160be5f8

data/README.md

@@ -4,6 +4,8 @@
 
 # Analytic
 
+![Demo](https://raw.githubusercontent.com/ksylvest/analytic/refs/heads/main/demo.png)
+
 Analytic provides visitor / session / view tracking without the need for any third-party service.
 
 ## Installation
@@ -21,13 +23,6 @@ Rails.application.routes.draw do
 end
 ```
 
-```ruby
-# config/initializer/analytic.rb
-Analytic.configure do |config|
-  config.timezone = Time.find_zone('Canada/Pacific') # default is `Time.zone`
-end
-```
-
 ## Usage
 
 Default inline tracking is configured with:
@@ -36,7 +31,7 @@ Default inline tracking is configured with:
 class ApplicationController
   include Analytic::Trackable
 
-  before_action { analytic_track! }
+  before_action :analytic_track!, if: -> { request.format.html? }
 end
 ```
 
@@ -46,11 +41,105 @@ Alternative job tracking is configured with:
 class ApplicationController
   include Analytic::Trackable
 
-  before_action { analytic_enqueue_track_job! }
+  before_action :analytic_enqueue_track_job!, if: -> { request.format.html? }
+end
 ```
 
 _note: a queue such as sidekiq, rescue, etc must be running to see tracking_
 
+## Configuration
+
+### Authentication the Dashboard
+
+By default **Analytic** is not authenticated. To authenticate using `Rack::Auth` generate a random username and password:
+
+```ruby
+$ bin/rails secret # generate a secret
+$ bin/rails credentials:edit
+```
+
+```yaml
+analytic:
+  username: abc...
+  password: def...
+```
+
+```ruby
+# config/initializers/analytic.rb
+
+def same?(src, dst)
+  # https://api.rubyonrails.org/classes/ActiveSupport/SecurityUtils.html
+  ActiveSupport::SecurityUtils.secure_compare(src, dst)
+end
+
+Analytic.configure do |config|
+  unless Rails.env.local?
+    config.use Rack::Auth::Basic do |username, password|
+      credentials = Rails.application.credentials.analytic
+      same?(username, credentials.username) && same?(password, credentials.password)
+    end
+  end
+end
+```
+
+### Capturing Extra Parameters
+
+By default **Analytic** tracks `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `ref` and `source` parameters for each request. This list can be customized using:
+
+```ruby
+# config/initializer/analytic.rb
+Analytic.configure do |config|
+  config.params << :gclid # e.g. Google
+  config.params << :msclkid # e.g. Bing
+end
+```
+
+### Changing the Time Zone
+
+By default **Analytic** uses `Time.zone`. The time zone can be changed using:
+
+```ruby
+# config/application.rb
+class Application < Rails::Application
+  config.time_zone = 'Canada/Pacific'
+end
+```
+
+The time zone may also be specified for **Analytic** using any `ActiveSupport::TimeZone`:
+
+```ruby
+# config/initializer/analytic.rb
+Analytic.configure do |config|
+  config.time_zone = Time.find_zone('Canada/Pacific')
+end
+```
+
+### Changing the Database
+
+By default **Analytic** uses your apps main database. The database can be changed using:
+
+```ruby
+# config/initializer/analytic.rb
+Analytic.configure do |config|
+  config.connects_to = { database: { writing: :primary, reading: :replica } }
+end
+```
+
+### Overriding IP Masking Rules
+
+By default IP addresses are masked as follows:
+
+- IPv4: limit to leading 24-bits (e.g. '255.255.255.255' becomes '255.255.255.0')
+- IPv6: limit to leading 48-bits (e.g. 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff' becomes 'ffff:ffff:ffff:0000:0000:0000:0000:0000')
+
+To override both an `ip_v4_mask` and `ip_v6_mask` are assignable:
+
+```ruby
+Analytic.configure do |config|
+  config.ip_v4_mask = 24 # nil skips masking
+  config.ip_v6_mask = 48 # nil skips masking
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -10,4 +10,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 RuboCop::RakeTask.new
 
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
 task default: %i[spec rubocop]

data/app/assets/images/analytic/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512"><defs><linearGradient id="a" x1="0%" x2="100%" y1="100%" y2="0%"><stop offset="0%" stop-color="#06B6D4"/><stop offset="49.9%" stop-color="#6366F1"/><stop offset="100%" stop-color="#D946EF"/></linearGradient></defs><g fill="none" fill-rule="evenodd"><rect width="512" height="512" fill="url(#a)" rx="256"/><circle cx="256" cy="256" r="184" stroke="#FFF" stroke-width="48"/><rect width="48" height="128" x="232" y="210" fill="#FFF" rx="16"/><rect width="48" height="96" x="168" y="242" fill="#FFF" rx="16"/><rect width="48" height="164" x="296" y="174" fill="#FFF" rx="16"/></g></svg>

data/app/controllers/analytic/dashboard_controller.rb

@@ -3,7 +3,8 @@
 module Analytic
   class DashboardController < ApplicationController
     include Analytic::Trackable
-    before_action { analytic_track! }
+
+    before_action :analytic_track!, if: -> { request.format.html? }
 
     # GET /
     def show

data/app/controllers/concerns/analytic/trackable.rb

@@ -3,25 +3,31 @@
 module Analytic
   module Trackable
     # @param params [Hash]
-    def analytic_track!(params: {})
-      Analytic::View.create!(
+    def analytic_track!
+      Analytic::Event.create!(
         timestamp: Time.current,
         session_id: analytic_session_id,
         visitor_id: analytic_visitor_id,
-        host: request.host,
-        path: request.path,
-        params:
+        ip: analytic_ip,
+        host: analytic_host,
+        path: analytic_path,
+        referrer: analytic_referrer,
+        user_agent: request.user_agent,
+        params: analytic_params
       )
     end
 
     # @param params [Hash]
-    def analytic_enqueue_track_job!(params: {})
+    def analytic_enqueue_track_job!
       Analytic::TrackJob.perform_later(
         session_id: analytic_session_id,
         visitor_id: analytic_visitor_id,
-        host: request.host,
-        path: request.path,
-        params:
+        ip: analytic_ip,
+        host: analytic_host,
+        path: analytic_path,
+        referrer: analytic_referrer,
+        user_agent: request.user_agent,
+        params: analytic_params
       )
     end
 
@@ -34,5 +40,40 @@ module Analytic
     def analytic_visitor_id
       cookies.permanent[:analytic_visitor_id] ||= SecureRandom.uuid
     end
+
+    # @return [IPAddr]
+    def analytic_ip
+      ip_addr = IPAddr.new(request.remote_ip)
+
+      return ip_addr.mask(Analytic.config.ip_v4_mask) if Analytic.config.ip_v4_mask? && ip_addr.ipv4?
+      return ip_addr.mask(Analytic.config.ip_v6_mask) if Analytic.config.ip_v6_mask? && ip_addr.ipv6?
+
+      ip_addr
+    end
+
+    # @return [String]
+    def analytic_host
+      request.host
+    end
+
+    # @return [String]
+    def analytic_path
+      request.path
+    end
+
+    # @return [String]
+    def analytic_referrer
+      request.referer
+    end
+
+    # @return [String]
+    def analytic_user_agent
+      request.user_agent
+    end
+
+    # @return [Hash]
+    def analytic_params
+      params.slice(*Analytic.config.params)
+    end
   end
 end

data/app/helpers/analytic/application_helper.rb

@@ -2,5 +2,47 @@
 
 module Analytic
   module ApplicationHelper
+    def react(component:)
+      tag.div(data: { react: component })
+    end
+
+    # @param icon [String] e.g. fa fa-user
+    def fa_icon_tag(icon)
+      tag.i(class: icon)
+    end
+
+    # @param delta [Float]
+    # @return [String]
+    def delta_icon_tag(delta)
+      if delta.zero?
+        fa_icon_tag('fa-solid fa-xmark')
+      elsif delta.positive?
+        fa_icon_tag('fa-solid fa-arrow-up')
+      elsif delta.negative?
+        fa_icon_tag('fa-solid fa-arrow-down')
+      end
+    end
+
+    # @param delta [Float]
+    # @return [String]
+    def delta_percentage_tag(delta)
+      tag.span(number_to_percentage(delta.abs * 100.0, precision: 2), class: 'delta__value')
+    end
+
+    # @param delta [Float, nil]
+    def delta_tag(delta)
+      return if delta.nil?
+
+      modifier =
+        if delta.zero? then 'delta--neutral'
+        elsif delta.positive? then 'delta--positive'
+        elsif delta.negative? then 'delta--negative'
+        end
+
+      tag.div(class: "delta #{modifier}") do
+        concat(delta_icon_tag(delta))
+        concat(delta_percentage_tag(delta))
+      end
+    end
   end
 end

data/app/jobs/analytic/track_job.rb

@@ -10,12 +10,14 @@ module Analytic
     # @param host [String]
     # @param path [String]
     # @param params [Hash]
-    def perform(session_id:, visitor_id:, host:, path:, timestamp: Time.current, params: {})
-      Analytic::View.create!(
+    def perform(session_id:, visitor_id:, host:, path:, ip:, timestamp: Time.current, params: {})
+      Analytic::Event.create!(
+        timestamp:,
         session_id:,
         visitor_id:,
         host:,
         path:,
+        ip:,
         params:
       )
     end

data/app/models/analytic/application_record.rb

@@ -3,5 +3,7 @@
 module Analytic
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
+
+    connects_to(**Analytic.config.connects_to) if Analytic.config.connects_to?
   end
 end

data/app/models/analytic/dashboard.rb

@@ -4,19 +4,40 @@ module Analytic
   class Dashboard
     PAGES_LIMIT = 8
 
+    # @return [String]
+    attr_reader :period
+
     # @param period [String] today, yesterday, week, month, year
     def initialize(period:)
       @period = period
     end
 
-    # @return [Integer]
-    delegate :count, to: :views
+    # @return [Stat]
+    def views
+      Stat.new(
+        current: current.count,
+        prior: prior&.count,
+        name: 'Views'
+      )
+    end
 
-    # @return [Integer]
-    delegate :distinct_visitors_count, to: :views
+    # @return [Stat]
+    def visitors
+      Stat.new(
+        current: current.distinct_visitors_count,
+        prior: prior&.distinct_visitors_count,
+        name: 'Visitors'
+      )
+    end
 
-    # @return [Integer]
-    delegate :distinct_sessions_count, to: :views
+    # @return [Stat]
+    def sessions
+      Stat.new(
+        current: current.distinct_sessions_count,
+        prior: prior&.distinct_sessions_count,
+        name: 'Sessions'
+      )
+    end
 
     # @return [String]
     def name
@@ -27,39 +48,50 @@ module Analytic
       end
     end
 
-    # @return [Array<Array(String, String, Integer)>]
-    def pages
-      views
-        .group(:host)
-        .group(:path)
-        .order(count: :desc)
-        .limit(PAGES_LIMIT)
-        .pluck(:host, :path, Arel.sql('COUNT(*) AS count'))
+    # @return [Period]
+    def current
+      @current ||= Period.new(range:)
     end
 
-    protected
+    # @return [Period]
+    def prior
+      return unless range?
+      return @prior if defined?(@prior)
 
-    # @return [Analytic::View::ActiveRecord_Relation]
-    def views
-      @views ||= Analytic::View.within(range)
+      @prior ||= Period.new(range: ((range.min - duration)..(range.max - duration)))
+    end
+
+    # @return [Boolean]
+    def range?
+      @period.present?
     end
 
     # @return [Range<Time>]
     def range
-      return unless @period
-
-      case @period
-      when 'today' then timezone.today.all_day
-      when 'yesterday' then timezone.yesterday.all_day
-      when 'week' then timezone.now.all_week
-      when 'month' then timezone.now.all_month
-      when 'year' then timezone.now.all_year
-      end
+      (now - duration)..now if range?
+    end
+
+    # @return [Interval]
+    def duration
+      @duration ||=
+        case @period
+        when '24h' then 24.hours
+        when '7d' then 7.days
+        when '4w' then 4.weeks
+        when '12m' then 12.months
+        end
+    end
+
+    protected
+
+    # @return [Time]
+    def now
+      @now ||= time_zone.now
     end
 
     # @return [ActiveSupport::TimeZone]
-    def timezone
-      Analytic.config.timezone || Time.zone
+    def time_zone
+      @time_zone ||= Analytic.config.time_zone || Time.zone
     end
   end
 end

data/app/models/analytic/{view.rb → event.rb}

@@ -1,23 +1,24 @@
 # frozen_string_literal: true
 
 module Analytic
-  class View < ApplicationRecord
+  class Event < ApplicationRecord
     validates :timestamp, presence: true
     validates :visitor_id, presence: true
     validates :session_id, presence: true
     validates :path, presence: true
     validates :host, presence: true
+    validates :ip, presence: true
 
     scope :within, ->(range) { where(timestamp: range) if range }
 
     # @return [Integer]
     def self.distinct_visitors_count
-      count('DISTINCT "analytic_views"."visitor_id"')
+      count('DISTINCT "analytic_events"."visitor_id"')
     end
 
     # @return [Integer]
     def self.distinct_sessions_count
-      count('DISTINCT "analytic_views"."session_id"')
+      count('DISTINCT "analytic_events"."session_id"')
     end
   end
 end

data/app/models/analytic/period.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Analytic
+  class Period
+    PAGES_LIMIT = 8
+
+    # @return [Range <Time>]
+    attr_accessor :range
+
+    # @param dates [Range<Time>]
+    def initialize(range:)
+      @range = range
+    end
+
+    # @return [Integer]
+    delegate :count, to: :views
+
+    # @return [Integer]
+    delegate :distinct_visitors_count, to: :views
+
+    # @return [Integer]
+    delegate :distinct_sessions_count, to: :views
+
+    # @return [Array<Array(String, String, Integer)>]
+    def pages
+      views
+        .group(:host)
+        .group(:path)
+        .order(count: :desc)
+        .limit(PAGES_LIMIT)
+        .pluck(:host, :path, Arel.sql('COUNT(*) AS count'))
+    end
+
+    protected
+
+    # @return [Analytic::Event::ActiveRecord_Relation]
+    def views
+      @views ||= Analytic::Event.within(@range)
+    end
+  end
+end

data/app/models/analytic/stat.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Analytic
+  class Stat
+    # @param current [Integer]
+    # @param prior [Integer]
+    # @param name [String]
+    def initialize(current:, prior:, name:)
+      @current = current
+      @prior = prior
+      @name = name
+    end
+
+    # @return [Integer]
+    def count
+      @current
+    end
+
+    # e.g. prior = 4 / current = 5 / delta = + 0.25
+    # e.g. prior = 4 / current = 3 / delta = - 0.25
+    #
+    # @return [Float, nil]
+    def delta
+      return if @prior.nil?
+      return if @prior.zero?
+
+      (@current - @prior).fdiv(@prior)
+    end
+  end
+end