analytic 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc45200aa3d02b6b5b0762abc37f93924ea4d025c25ddd671933512b35a2a795
-  data.tar.gz: 925779556b411685139ff5d8c167bee45b4aed9ec793c523f90a26fcc95685df
+  metadata.gz: e283c032e4bc20c3b16244bee1b0a4b65e236626bdd9d75c05ef44116c6aa679
+  data.tar.gz: 8f9e592c750579ed57665364b2b9f0fd5c7cf6455e68e134e1b7817eda7c2713
 SHA512:
-  metadata.gz: 5e1b269cd08c02ae021f491b3b5dd6076e7be3fe049b1bf50ea4b4ef09ac50ce32dd50c73f16cdd549ed416a1f59b602b8ed4b9994ed6690623559ab14aca8a9
-  data.tar.gz: 34eea881684f27d927c48c7b3c76240a946cca6551747342017c5f5e9f53c558f391c5c66592ceb8f701af86c0639742fb6d592270a55680a87b6b6684084e22
+  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,15 +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`
-  config.ip_v4_mask = 24 # '255.255.255.255' becomes '255.255.255.0'
-  config.ip_v6_mask = 48 # 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff' becomes 'ffff:ffff:ffff:0000:0000:0000:0000:0000'
-end
-```
-
 ## Usage
 
 Default inline tracking is configured with:
@@ -38,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
 ```
 
@@ -48,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

@@ -4,7 +4,7 @@ module Analytic
   module Trackable
     # @param params [Hash]
     def analytic_track!
-      Analytic::View.create!(
+      Analytic::Event.create!(
         timestamp: Time.current,
         session_id: analytic_session_id,
         visitor_id: analytic_visitor_id,
@@ -73,7 +73,7 @@ module Analytic
 
     # @return [Hash]
     def analytic_params
-      params.permit(:utm_source, :utm_medium, :utm_campaign, :utm_term, :utm_content)
+      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

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

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,7 +1,7 @@
 # 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
@@ -13,12 +13,12 @@ module Analytic
 
     # @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

data/app/packs/analytic/application/components/chart.tsx

@@ -0,0 +1,148 @@
+import { useMemo, type FC } from "react";
+
+import { Group } from "@visx/group";
+import { Bar } from "@visx/shape";
+import { scaleBand, scaleLinear } from "@visx/scale";
+import { AxisBottom, AxisLeft } from "@visx/axis";
+import { GridColumns, GridRows } from "@visx/grid";
+import { ParentSize } from "@visx/responsive";
+
+const BAR_BG = "#6366f1"; // indigo-500
+const CHART_BG = "#f8fafc"; // slate-50
+const GRID_COLOR = "#e2e8f0"; // slate-200
+const AXIS_TICK_COLOR = GRID_COLOR;
+const AXIS_LINE_COLOR = GRID_COLOR;
+
+const CHART_ML = 60; // px
+const CHART_MB = 60; // px
+const CHART_MT = 40; // px
+const CHART_MR = 40; // px
+
+const TICK_LABEL_PROPS = {
+  fill: "#718096", // slate-600
+  fontSize: 10,
+  fontFamily: `"ui-sans-serif", "system-ui", "sans-serif"`,
+} as const;
+
+type Entry = {
+  label: string;
+  value: number;
+};
+
+const ENTRIES: Entry[] = [
+  { label: "Jan, 2024", value: 404 },
+  { label: "Feb, 2024", value: 303 },
+  { label: "Mar, 2024", value: 250 },
+  { label: "Apr, 2024", value: 304 },
+  { label: "May, 2024", value: 404 },
+  { label: "Jun, 2024", value: 604 },
+];
+
+const Bars: FC<{
+  width: number;
+  height: number;
+  entries: Entry[];
+}> = ({ width, height, entries }) => {
+  const xScale = useMemo(
+    () =>
+      scaleBand<string>({
+        range: [0, width],
+        round: true,
+        domain: entries.map(({ label }) => label),
+        padding: 0.4,
+      }),
+    [width]
+  );
+  const yScale = useMemo(
+    () =>
+      scaleLinear<number>({
+        range: [height, 0],
+        round: true,
+        domain: [0, Math.max(...entries.map(({ value }) => value))],
+      }),
+    [height]
+  );
+
+  return (
+    <>
+      <GridRows
+        scale={yScale}
+        width={width}
+        height={height}
+        stroke={GRID_COLOR}
+      />
+
+      <GridColumns
+        scale={xScale}
+        width={width}
+        height={height}
+        stroke={GRID_COLOR}
+      />
+
+      {entries.map((entry, index) => {
+        const barWidth = xScale.bandwidth();
+        const barHeight = height - yScale(entry.value);
+        const barX = xScale(entry.label);
+        const barY = height - barHeight;
+
+        return (
+          <Bar
+            key={index}
+            x={barX}
+            y={barY}
+            rx={8}
+            ry={8}
+            width={barWidth}
+            height={barHeight}
+            fill={BAR_BG}
+          />
+        );
+      })}
+
+      <AxisBottom
+        top={height}
+        scale={xScale}
+        stroke={AXIS_LINE_COLOR}
+        tickStroke={AXIS_TICK_COLOR}
+        tickLabelProps={TICK_LABEL_PROPS}
+      />
+
+      <AxisLeft
+        left={0}
+        scale={yScale}
+        stroke={AXIS_LINE_COLOR}
+        tickStroke={AXIS_TICK_COLOR}
+        tickLabelProps={TICK_LABEL_PROPS}
+      />
+    </>
+  );
+};
+
+export const Chart: FC<{
+  height?: number;
+  entries?: Entry[];
+}> = ({ height = 300, entries = ENTRIES }) => (
+  <ParentSize>
+    {({ width }) => (
+      <svg width={width} height={height}>
+        <rect
+          x={0}
+          y={0}
+          rx={4}
+          ry={4}
+          width={width}
+          height={height}
+          fill={CHART_BG}
+        />
+
+        <Group top={CHART_MT} left={CHART_ML}>
+          <Bars
+            width={width - CHART_MR - CHART_ML}
+            height={height - CHART_MT - CHART_MB}
+            entries={entries}
+          />
+        </Group>
+      </svg>
+    )}
+  </ParentSize>
+);

data/app/packs/analytic/application/components/index.tsx

@@ -0,0 +1,21 @@
+import { type FC } from "react";
+
+import { Chart } from "./chart";
+import { createRoot } from "react-dom/client";
+
+const COMPONENTS: Record<string, FC> = {
+  Chart,
+};
+
+document.addEventListener("DOMContentLoaded", () => {
+  const elements = document.querySelectorAll("[data-react]");
+  for (const element of elements) {
+    const root = createRoot(element);
+
+    const name = element.getAttribute("data-react");
+
+    const Component = COMPONENTS[name!];
+
+    root.render(<Component />);
+  }
+});

data/app/packs/analytic/application/index.ts

@@ -1 +1,2 @@
 import "./initializers";
+import "./components";

data/app/packs/analytic/application/initializers/fontawesome.ts

@@ -10,14 +10,20 @@ import { faGlobe } from "@fortawesome/free-solid-svg-icons/faGlobe";
 import { faHouse } from "@fortawesome/free-solid-svg-icons/faHouse";
 import { faSliders } from "@fortawesome/free-solid-svg-icons/faSliders";
 import { faUsers } from "@fortawesome/free-solid-svg-icons/faUsers";
+import { faArrowUp } from "@fortawesome/free-solid-svg-icons/faArrowUp";
+import { faArrowDown } from "@fortawesome/free-solid-svg-icons/faArrowDown";
+import { faXmark } from "@fortawesome/free-solid-svg-icons/faXmark";
 
 library.add(
+  faArrowDown,
+  faArrowUp,
   faClock,
   faEye,
+  faFileCode,
   faGauge,
   faGlobe,
   faHouse,
   faSliders,
   faUsers,
-  faFileCode
+  faXmark
 );