behavior_analytics 2.2.1 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bead5d234d7e827224b697cda617f6ce4e78839e34e419350fc91a9b1c50732d
-  data.tar.gz: 0c6bf809b8321a256f15d3830d43c2d9955acb9c946cee6dfe7a884603b3037a
+  metadata.gz: 658a8852d807dd03e050e0c773ff213459e168dfd37ecb14d707d381ada8362b
+  data.tar.gz: c7398303e1217051c62384c7ac78e6c43dc5da35ed689917d7b5bab99b4f4b41
 SHA512:
-  metadata.gz: 29c2f5c9e7897e5d3bddda1c64f2cc67b9950c69581435c0dfbf98574f6bc2fc74954685b81499f19f58f62f5754c1c4a846dc4f79029e78ac2b799380be34a6
-  data.tar.gz: fa54c278f349cafb3068c388c4e9ca2d34bfd091a88a549ee431fc2546604da4b8a84578f362adc24e546ae6122613cadc524d40aa7444d76f9e50de417543f6
+  metadata.gz: a795b6a6ca62eebe154b73a7a5b3377e1b305b7c1fce76e8da2acecc4535a69e34fe39914b4491a014929d55121848a06706f0d2c111262f4661453b08b7c4f9
+  data.tar.gz: 237f9c73911e9c42cf1922158e9724f094a32fffee340077046509f3b966495af9e4d1f4bf3db442e4f9ac0ccb8a688927f9bf3db5b099d0be434ff5255bb52d

data/db/migrate/003_create_behavior_visits.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class CreateBehaviorVisits < ActiveRecord::Migration[7.0]
+  def change
+    create_table :behavior_visits do |t|
+      t.string :visit_token, null: false, index: true
+      t.string :visitor_token, null: false, index: true
+      t.string :tenant_id, index: true
+      t.string :user_id, index: true
+      t.string :ip
+      t.text :user_agent
+      t.string :referrer
+      t.string :landing_page
+      t.string :browser
+      t.string :os
+      t.string :device_type
+      t.string :country
+      t.string :city
+      t.string :utm_source
+      t.string :utm_medium
+      t.string :utm_campaign
+      t.string :utm_term
+      t.string :utm_content
+      t.string :referring_domain
+      t.string :search_keyword
+      t.datetime :started_at, null: false
+      t.datetime :ended_at
+      t.datetime :created_at, null: false
+      t.datetime :updated_at, null: false
+    end
+
+    add_index :behavior_visits, [:tenant_id, :started_at]
+    add_index :behavior_visits, [:visitor_token, :started_at]
+    add_index :behavior_visits, [:user_id, :started_at]
+    add_index :behavior_visits, [:visit_token, :visitor_token]
+  end
+end
+

data/db/migrate/004_add_visit_fields_to_events.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddVisitFieldsToEvents < ActiveRecord::Migration[7.0]
+  def change
+    add_column :behavior_events, :visit_id, :string, index: true unless column_exists?(:behavior_events, :visit_id)
+    add_column :behavior_events, :visitor_id, :string, index: true unless column_exists?(:behavior_events, :visitor_id)
+    
+    add_index :behavior_events, [:visit_id, :created_at] unless index_exists?(:behavior_events, [:visit_id, :created_at])
+    add_index :behavior_events, [:visitor_id, :created_at] unless index_exists?(:behavior_events, [:visitor_id, :created_at])
+  end
+end
+

data/lib/behavior_analytics/analytics/geographic.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Analytics
+    class Geographic
+      attr_reader :storage_adapter
+
+      def initialize(storage_adapter:)
+        @storage_adapter = storage_adapter
+      end
+
+      def country_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:country] }
+              .map { |country, visits| { country: country, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def city_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:city] }
+              .map { |city, visits| { city: city, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def country_city_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| [v[:country], v[:city]] }
+              .map { |(country, city), visits| { country: country, city: city, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def device_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:device_type] }
+              .map { |device, visits| { device: device, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def browser_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:browser] }
+              .map { |browser, visits| { browser: browser, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/analytics/referrer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module BehaviorAnalytics
+  module Analytics
+    class Referrer
+      attr_reader :storage_adapter
+
+      def initialize(storage_adapter:)
+        @storage_adapter = storage_adapter
+      end
+
+      def source_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| extract_source(v[:referrer]) }
+              .map { |source, visits| { source: source || "direct", count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def utm_source_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:utm_source] }
+              .map { |source, visits| { utm_source: source || "none", count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def utm_campaign_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:utm_campaign] }
+              .map { |campaign, visits| { utm_campaign: campaign || "none", count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def search_keyword_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.select { |v| v[:search_keyword] }
+              .group_by { |v| v[:search_keyword] }
+              .map { |keyword, visits| { keyword: keyword, count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      def referring_domain_breakdown(context, options = {})
+        return [] unless storage_adapter.respond_to?(:query_visits)
+        
+        visits = storage_adapter.query_visits(context, options)
+        visits.group_by { |v| v[:referring_domain] }
+              .map { |domain, visits| { domain: domain || "direct", count: visits.size } }
+              .sort_by { |r| -r[:count] }
+      end
+
+      private
+
+      def extract_source(referrer)
+        return nil unless referrer
+        
+        uri = URI.parse(referrer) rescue nil
+        return nil unless uri
+        
+        host = uri.host&.downcase
+        return "google" if host&.include?("google")
+        return "bing" if host&.include?("bing")
+        return "yahoo" if host&.include?("yahoo")
+        return "facebook" if host&.include?("facebook")
+        return "twitter" if host&.include?("twitter") || host&.include?("x.com")
+        return "linkedin" if host&.include?("linkedin")
+        return "reddit" if host&.include?("reddit")
+        
+        host
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/cleanup/retention_policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Cleanup
+    class RetentionPolicy
+      attr_reader :visit_retention_days, :event_retention_days
+
+      def initialize(visit_retention_days: 90, event_retention_days: 365)
+        @visit_retention_days = visit_retention_days
+        @event_retention_days = event_retention_days
+      end
+
+      def should_delete_visit?(visit)
+        return false unless visit[:started_at] || visit[:created_at]
+        
+        visit_date = visit[:started_at] || visit[:created_at]
+        cutoff_date = visit_retention_days.days.ago
+        
+        visit_date < cutoff_date
+      end
+
+      def should_delete_event?(event)
+        return false unless event[:created_at]
+        
+        cutoff_date = event_retention_days.days.ago
+        event[:created_at] < cutoff_date
+      end
+
+      def visits_cutoff_date
+        visit_retention_days.days.ago
+      end
+
+      def events_cutoff_date
+        event_retention_days.days.ago
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/cleanup/scheduler.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Cleanup
+    class Scheduler
+      attr_reader :storage_adapter, :retention_policy
+
+      def initialize(storage_adapter:, retention_policy:)
+        @storage_adapter = storage_adapter
+        @retention_policy = retention_policy
+      end
+
+      def cleanup_visits
+        return unless storage_adapter.respond_to?(:delete_old_visits)
+        
+        cutoff_date = retention_policy.visits_cutoff_date
+        deleted_count = storage_adapter.delete_old_visits(cutoff_date)
+        
+        BehaviorAnalytics.configuration.debug("Deleted #{deleted_count} old visits", context: { cutoff_date: cutoff_date })
+        deleted_count
+      end
+
+      def cleanup_events
+        return unless storage_adapter.respond_to?(:delete_old_events)
+        
+        cutoff_date = retention_policy.events_cutoff_date
+        deleted_count = storage_adapter.delete_old_events(cutoff_date)
+        
+        BehaviorAnalytics.configuration.debug("Deleted #{deleted_count} old events", context: { cutoff_date: cutoff_date })
+        deleted_count
+      end
+
+      def cleanup_all
+        {
+          visits: cleanup_visits,
+          events: cleanup_events
+        }
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/detection/device_detector.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Detection
+    class DeviceDetector
+      def initialize(strategy: :simple)
+        @strategy = strategy
+      end
+
+      def detect(user_agent)
+        return {} unless user_agent
+
+        case @strategy
+        when :browser
+          detect_with_browser_gem(user_agent)
+        when :user_agent_parser
+          detect_with_user_agent_parser(user_agent)
+        else
+          detect_simple(user_agent)
+        end
+      end
+
+      private
+
+      def detect_simple(user_agent)
+        ua = user_agent.downcase
+        result = {
+          browser: detect_browser(ua),
+          os: detect_os(ua),
+          device_type: detect_device_type(ua)
+        }
+        result.compact
+      end
+
+      def detect_browser(ua)
+        return "Chrome" if ua.include?("chrome") && !ua.include?("edg")
+        return "Safari" if ua.include?("safari") && !ua.include?("chrome")
+        return "Firefox" if ua.include?("firefox")
+        return "Edge" if ua.include?("edg")
+        return "Opera" if ua.include?("opera") || ua.include?("opr")
+        return "Internet Explorer" if ua.include?("msie") || ua.include?("trident")
+        "Unknown"
+      end
+
+      def detect_os(ua)
+        return "iOS" if ua.include?("iphone") || ua.include?("ipad") || ua.include?("ipod")
+        return "Android" if ua.include?("android")
+        return "Windows" if ua.include?("windows")
+        return "Mac OS" if ua.include?("mac os") || ua.include?("macintosh")
+        return "Linux" if ua.include?("linux")
+        return "Unix" if ua.include?("unix")
+        "Unknown"
+      end
+
+      def detect_device_type(ua)
+        ua_lower = ua.downcase
+        return "mobile" if ua_lower.include?("mobile") || ua_lower.include?("iphone") || ua_lower.include?("android")
+        return "tablet" if ua_lower.include?("tablet") || ua_lower.include?("ipad")
+        return "desktop" if ua_lower.include?("windows") || ua_lower.include?("mac") || ua_lower.include?("linux")
+        "unknown"
+      end
+
+      def detect_with_browser_gem(user_agent)
+        begin
+          require "browser"
+          browser = Browser.new(user_agent)
+          {
+            browser: browser.name,
+            browser_version: browser.version,
+            os: browser.platform.name,
+            os_version: browser.platform.version,
+            device_type: browser.device.mobile? ? "mobile" : (browser.device.tablet? ? "tablet" : "desktop")
+          }
+        rescue LoadError, StandardError
+          detect_simple(user_agent)
+        end
+      end
+
+      def detect_with_user_agent_parser(user_agent)
+        begin
+          require "user_agent_parser"
+          parser = UserAgentParser.parse(user_agent)
+          {
+            browser: parser.family,
+            browser_version: parser.version.to_s,
+            os: parser.os&.family,
+            os_version: parser.os&.version&.to_s,
+            device_type: detect_device_type_from_parser(parser)
+          }
+        rescue LoadError, StandardError
+          detect_simple(user_agent)
+        end
+      end
+
+      def detect_device_type_from_parser(parser)
+        device = parser.device
+        return "mobile" if device&.family&.downcase&.include?("mobile")
+        return "tablet" if device&.family&.downcase&.include?("tablet")
+        "desktop"
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/detection/geolocation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Detection
+    class Geolocation
+      def initialize(strategy: :simple)
+        @strategy = strategy
+      end
+
+      def detect(ip_address)
+        return {} unless ip_address
+        return {} if ip_address == "127.0.0.1" || ip_address == "::1" || ip_address.start_with?("192.168.") || ip_address.start_with?("10.")
+
+        case @strategy
+        when :geocoder
+          detect_with_geocoder(ip_address)
+        when :maxmind
+          detect_with_maxmind(ip_address)
+        else
+          detect_simple(ip_address)
+        end
+      end
+
+      private
+
+      def detect_simple(ip_address)
+        # Simple detection - returns empty for now
+        # In production, you'd want to use a proper geolocation service
+        {}
+      end
+
+      def detect_with_geocoder(ip_address)
+        begin
+          require "geocoder"
+          result = Geocoder.search(ip_address).first
+          return {} unless result
+
+          {
+            country: result.country,
+            country_code: result.country_code,
+            city: result.city,
+            region: result.region,
+            latitude: result.latitude,
+            longitude: result.longitude,
+            timezone: result.data&.dig("timezone")
+          }.compact
+        rescue LoadError, StandardError => e
+          BehaviorAnalytics.configuration.log_error(e, context: { ip: ip_address }) if BehaviorAnalytics.configuration.debug_mode
+          {}
+        end
+      end
+
+      def detect_with_maxmind(ip_address)
+        begin
+          require "maxminddb"
+          # This would require MaxMind GeoIP2 database
+          # For now, return empty - users can implement their own
+          {}
+        rescue LoadError, StandardError => e
+          BehaviorAnalytics.configuration.log_error(e, context: { ip: ip_address }) if BehaviorAnalytics.configuration.debug_mode
+          {}
+        end
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/helpers/tracking_helper.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Helpers
+    module TrackingHelper
+      def track_event(event_name, properties: {}, event_type: :custom, **options)
+        context = resolve_tracking_context
+        return unless context&.valid?
+
+        tracker.track(
+          context: context,
+          event_name: event_name,
+          event_type: event_type,
+          metadata: properties,
+          **options
+        )
+      end
+
+      def track_page_view(path: nil, properties: {}, **options)
+        path ||= request.path if respond_to?(:request)
+        track_event("page_view", properties: { path: path }.merge(properties), **options)
+      end
+
+      def track_click(element:, properties: {}, **options)
+        track_event("click", properties: { element: element }.merge(properties), **options)
+      end
+
+      def track_form_submit(form_name:, properties: {}, **options)
+        track_event("form_submit", properties: { form_name: form_name }.merge(properties), **options)
+      end
+
+      def track_conversion(conversion_name:, value: nil, properties: {}, **options)
+        props = { conversion_name: conversion_name }
+        props[:value] = value if value
+        track_event("conversion", properties: props.merge(properties), **options)
+      end
+
+      private
+
+      def resolve_tracking_context
+        # Try to resolve context from current request/controller
+        if respond_to?(:current_user, true)
+          Context.new(
+            tenant_id: respond_to?(:current_tenant, true) ? current_tenant&.id : BehaviorAnalytics.configuration.default_tenant_id,
+            user_id: current_user&.id,
+            user_type: current_user&.account_type || current_user&.user_type
+          )
+        elsif respond_to?(:request, true) && request.respond_to?(:remote_ip)
+          # Anonymous tracking
+          Context.new(
+            tenant_id: BehaviorAnalytics.configuration.default_tenant_id
+          )
+        else
+          # Fallback to default context
+          Context.new(
+            tenant_id: BehaviorAnalytics.configuration.default_tenant_id
+          )
+        end
+      end
+
+      def tracker
+        @tracker ||= BehaviorAnalytics.create_tracker
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/identification/user_resolver.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Identification
+    class UserResolver
+      attr_reader :visit_manager
+
+      def initialize(visit_manager:)
+        @visit_manager = visit_manager
+      end
+
+      def identify_user(user_id, visitor_token: nil, request: nil)
+        return unless user_id
+
+        # If visitor_token is provided, link all anonymous visits to this user
+        if visitor_token
+          visit_manager.link_user_to_visits(visitor_token, user_id)
+        elsif request
+          # Try to get visitor token from request
+          visitor_token = get_visitor_token_from_request(request)
+          visit_manager.link_user_to_visits(visitor_token, user_id) if visitor_token
+        end
+      end
+
+      def merge_visits(visitor_token, user_id)
+        visit_manager.link_user_to_visits(visitor_token, user_id)
+      end
+
+      def get_visitor_token_from_request(request)
+        # Try cookie first
+        if request.respond_to?(:cookies)
+          token = request.cookies["behavior_visitor_token"]
+          return token if token && !token.empty?
+        end
+
+        # Try header
+        if request.respond_to?(:headers)
+          token = request.headers["X-Visitor-Token"]
+          return token if token && !token.empty?
+        end
+
+        nil
+      end
+
+      def get_user_visits(user_id, limit: 100)
+        visit_manager.find_visits_by_user(user_id, limit: limit)
+      end
+
+      def get_visitor_visits(visitor_token, limit: 100)
+        visit_manager.find_visits_by_visitor(visitor_token, limit: limit)
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/javascript/client.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Javascript
+    class Client
+      def self.generate_script(tracker_url: "/behavior_analytics/track", auto_track: true)
+        <<~JAVASCRIPT
+          (function() {
+            var BehaviorAnalytics = {
+              trackerUrl: '#{tracker_url}',
+              visitorToken: null,
+              visitToken: null,
+              
+              init: function() {
+                this.loadVisitorToken();
+                #{'this.autoTrack();' if auto_track}
+              },
+              
+              loadVisitorToken: function() {
+                var token = this.getCookie('behavior_visitor_token');
+                if (!token) {
+                  token = this.generateToken();
+                  this.setCookie('behavior_visitor_token', token, 730); // 2 years
+                }
+                this.visitorToken = token;
+              },
+              
+              generateToken: function() {
+                return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+                  var r = Math.random() * 16 | 0;
+                  var v = c == 'x' ? r : (r & 0x3 | 0x8);
+                  return v.toString(16);
+                });
+              },
+              
+              setCookie: function(name, value, days) {
+                var expires = '';
+                if (days) {
+                  var date = new Date();
+                  date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
+                  expires = '; expires=' + date.toUTCString();
+                }
+                document.cookie = name + '=' + (value || '') + expires + '; path=/; SameSite=Lax';
+              },
+              
+              getCookie: function(name) {
+                var nameEQ = name + '=';
+                var ca = document.cookie.split(';');
+                for (var i = 0; i < ca.length; i++) {
+                  var c = ca[i];
+                  while (c.charAt(0) == ' ') c = c.substring(1, c.length);
+                  if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
+                }
+                return null;
+              },
+              
+              track: function(eventName, properties) {
+                var payload = {
+                  event_name: eventName,
+                  properties: properties || {},
+                  visitor_token: this.visitorToken,
+                  visit_token: this.visitToken,
+                  page: window.location.pathname,
+                  referrer: document.referrer,
+                  user_agent: navigator.userAgent,
+                  timestamp: new Date().toISOString()
+                };
+                
+                this.sendRequest(payload);
+              },
+              
+              trackPageView: function() {
+                this.track('page_view', {
+                  path: window.location.pathname,
+                  title: document.title,
+                  referrer: document.referrer
+                });
+              },
+              
+              trackClick: function(element, properties) {
+                var props = {
+                  element: element.tagName.toLowerCase(),
+                  id: element.id || null,
+                  class: element.className || null,
+                  text: element.textContent ? element.textContent.substring(0, 100) : null
+                };
+                
+                if (properties) {
+                  Object.assign(props, properties);
+                }
+                
+                this.track('click', props);
+              },
+              
+              autoTrack: function() {
+                var self = this;
+                
+                // Track page view on load
+                if (document.readyState === 'loading') {
+                  document.addEventListener('DOMContentLoaded', function() {
+                    self.trackPageView();
+                  });
+                } else {
+                  this.trackPageView();
+                }
+                
+                // Track clicks on elements with data-track attribute
+                document.addEventListener('click', function(e) {
+                  var element = e.target;
+                  if (element.hasAttribute('data-track')) {
+                    var trackValue = element.getAttribute('data-track');
+                    var properties = {};
+                    
+                    if (element.hasAttribute('data-track-properties')) {
+                      try {
+                        properties = JSON.parse(element.getAttribute('data-track-properties'));
+                      } catch (e) {}
+                    }
+                    
+                    self.track(trackValue || 'click', properties);
+                  }
+                });
+                
+                // Track form submissions
+                document.addEventListener('submit', function(e) {
+                  var form = e.target;
+                  if (form.tagName === 'FORM' && form.hasAttribute('data-track')) {
+                    var trackValue = form.getAttribute('data-track');
+                    self.track(trackValue || 'form_submit', {
+                      form_id: form.id || null,
+                      form_action: form.action || null
+                    });
+                  }
+                });
+              },
+              
+              sendRequest: function(payload) {
+                if (navigator.sendBeacon) {
+                  var blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
+                  navigator.sendBeacon(this.trackerUrl, blob);
+                } else {
+                  var xhr = new XMLHttpRequest();
+                  xhr.open('POST', this.trackerUrl, true);
+                  xhr.setRequestHeader('Content-Type', 'application/json');
+                  xhr.send(JSON.stringify(payload));
+                }
+              }
+            };
+            
+            // Initialize on load
+            if (document.readyState === 'loading') {
+              document.addEventListener('DOMContentLoaded', function() {
+                BehaviorAnalytics.init();
+              });
+            } else {
+              BehaviorAnalytics.init();
+            }
+            
+            // Expose globally
+            window.BehaviorAnalytics = BehaviorAnalytics;
+          })();
+        JAVASCRIPT
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BehaviorAnalytics
-  VERSION = "2.2.1"
+  VERSION = "2.2.2"
 end

data/lib/behavior_analytics/visits/auto_creator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Visits
+    class AutoCreator
+      attr_reader :manager, :cookie_name
+
+      def initialize(manager:, cookie_name: "behavior_visitor_token")
+        @manager = manager
+        @cookie_name = cookie_name
+      end
+
+      def get_or_create_visit(request:, tenant_id: nil, user_id: nil)
+        visitor_token = get_or_create_visitor_token(request)
+        
+        utm_params = extract_utm_params(request)
+        
+        manager.find_or_create_visit(
+          visitor_token: visitor_token,
+          tenant_id: tenant_id,
+          user_id: user_id,
+          ip: request.ip,
+          user_agent: request.user_agent,
+          referrer: request.referer,
+          landing_page: request.path,
+          utm_params: utm_params
+        )
+      end
+
+      def get_or_create_visitor_token(request)
+        # Try to get from cookie
+        if request.respond_to?(:cookies)
+          token = request.cookies[cookie_name]
+          return token if token && !token.empty?
+        end
+
+        # Try to get from headers (for API requests)
+        if request.respond_to?(:headers)
+          token = request.headers["X-Visitor-Token"]
+          return token if token && !token.empty?
+        end
+
+        # Generate new token
+        SecureRandom.hex(16)
+      end
+
+      def set_visitor_token_cookie(response, visitor_token)
+        return unless response.respond_to?(:set_cookie)
+        
+        # Set cookie for 2 years
+        secure = if defined?(Rails)
+          Rails.env.production?
+        else
+          ENV["RAILS_ENV"] == "production" || ENV["RACK_ENV"] == "production"
+        end
+        
+        response.set_cookie(
+          cookie_name,
+          value: visitor_token,
+          expires: 2.years.from_now,
+          httponly: true,
+          secure: secure,
+          same_site: :lax
+        )
+      end
+
+      private
+
+      def extract_utm_params(request)
+        params = {}
+        
+        if request.respond_to?(:params)
+          params[:utm_source] = request.params["utm_source"]
+          params[:utm_medium] = request.params["utm_medium"]
+          params[:utm_campaign] = request.params["utm_campaign"]
+          params[:utm_term] = request.params["utm_term"]
+          params[:utm_content] = request.params["utm_content"]
+        end
+
+        params.compact
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/visits/manager.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "uri"
+
+module BehaviorAnalytics
+  module Visits
+    class Manager
+      attr_reader :storage_adapter, :visit_duration
+
+      def initialize(storage_adapter:, visit_duration: 30.minutes, device_detector: nil, geolocation: nil)
+        @storage_adapter = storage_adapter
+        @visit_duration = visit_duration
+        @device_detector = device_detector
+        @geolocation = geolocation
+      end
+
+      def find_or_create_visit(visitor_token:, tenant_id: nil, user_id: nil, ip: nil, user_agent: nil, 
+                               referrer: nil, landing_page: nil, utm_params: {})
+        # Try to find active visit for this visitor
+        active_visit = find_active_visit(visitor_token, user_id)
+        
+        if active_visit && !active_visit.expired?(visit_duration)
+          # Update visit if user logged in
+          if user_id && active_visit.user_id.nil?
+            active_visit.user_id = user_id
+            save_visit(active_visit)
+          end
+          return active_visit
+        end
+
+        # Detect device and geolocation if enabled
+        device_info = {}
+        geo_info = {}
+        
+        if BehaviorAnalytics.configuration.track_device_info && @device_detector && user_agent
+          device_info = @device_detector.detect(user_agent)
+        end
+        
+        if BehaviorAnalytics.configuration.track_geolocation && @geolocation && ip
+          geo_info = @geolocation.detect(ip)
+        end
+
+        # Create new visit
+        visit = Visit.new(
+          visitor_token: visitor_token,
+          tenant_id: tenant_id || BehaviorAnalytics.configuration.default_tenant_id,
+          user_id: user_id,
+          ip: ip,
+          user_agent: user_agent,
+          referrer: referrer,
+          landing_page: landing_page || referrer,
+          browser: device_info[:browser],
+          os: device_info[:os],
+          device_type: device_info[:device_type],
+          country: geo_info[:country],
+          city: geo_info[:city],
+          utm_source: utm_params[:utm_source],
+          utm_medium: utm_params[:utm_medium],
+          utm_campaign: utm_params[:utm_campaign],
+          utm_term: utm_params[:utm_term],
+          utm_content: utm_params[:utm_content],
+          referring_domain: extract_domain(referrer),
+          search_keyword: extract_search_keyword(referrer)
+        )
+
+        save_visit(visit)
+        visit
+      end
+
+      def find_active_visit(visitor_token, user_id = nil)
+        return nil unless storage_adapter.respond_to?(:find_active_visit)
+        
+        visit_data = storage_adapter.find_active_visit(visitor_token, user_id, visit_duration)
+        return nil unless visit_data
+
+        Visit.new(visit_data)
+      end
+
+      def save_visit(visit)
+        if storage_adapter.respond_to?(:save_visit)
+          storage_adapter.save_visit(visit.to_h)
+        end
+      end
+
+      def end_visit(visit_token)
+        visit = find_visit_by_token(visit_token)
+        return unless visit
+
+        visit.end!
+        save_visit(visit)
+      end
+
+      def find_visit_by_token(visit_token)
+        return nil unless storage_adapter.respond_to?(:find_visit_by_token)
+        
+        visit_data = storage_adapter.find_visit_by_token(visit_token)
+        return nil unless visit_data
+
+        Visit.new(visit_data)
+      end
+
+      def link_user_to_visits(visitor_token, user_id)
+        return unless storage_adapter.respond_to?(:link_user_to_visits)
+        
+        storage_adapter.link_user_to_visits(visitor_token, user_id)
+      end
+
+      def find_visits_by_user(user_id, limit: 100)
+        return [] unless storage_adapter.respond_to?(:find_visits_by_user)
+        
+        visits_data = storage_adapter.find_visits_by_user(user_id, limit: limit)
+        visits_data.map { |data| Visit.new(data) }
+      end
+
+      def find_visits_by_visitor(visitor_token, limit: 100)
+        return [] unless storage_adapter.respond_to?(:find_visits_by_visitor)
+        
+        visits_data = storage_adapter.find_visits_by_visitor(visitor_token, limit: limit)
+        visits_data.map { |data| Visit.new(data) }
+      end
+
+      private
+
+      def extract_domain(url)
+        return nil unless url
+        URI.parse(url).host rescue nil
+      end
+
+      def extract_search_keyword(referrer)
+        return nil unless referrer
+        
+        uri = URI.parse(referrer) rescue nil
+        return nil unless uri
+        
+        # Extract from Google, Bing, etc.
+        if uri.host&.include?("google")
+          params = URI.decode_www_form(uri.query || "").to_h
+          params["q"] || params["query"]
+        elsif uri.host&.include?("bing")
+          params = URI.decode_www_form(uri.query || "").to_h
+          params["q"]
+        else
+          nil
+        end
+      end
+    end
+  end
+end
+

data/lib/behavior_analytics/visits/visit.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module BehaviorAnalytics
+  module Visits
+    class Visit
+      attr_accessor :visit_token, :visitor_token, :tenant_id, :user_id, :ip, :user_agent,
+                    :referrer, :landing_page, :browser, :os, :device_type, :country, :city,
+                    :utm_source, :utm_medium, :utm_campaign, :utm_term, :utm_content,
+                    :referring_domain, :search_keyword, :started_at, :ended_at, :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @visit_token = attributes[:visit_token] || SecureRandom.hex(16)
+        @visitor_token = attributes[:visitor_token] || SecureRandom.hex(16)
+        @tenant_id = attributes[:tenant_id]
+        @user_id = attributes[:user_id]
+        @ip = attributes[:ip]
+        @user_agent = attributes[:user_agent]
+        @referrer = attributes[:referrer]
+        @landing_page = attributes[:landing_page]
+        @browser = attributes[:browser]
+        @os = attributes[:os]
+        @device_type = attributes[:device_type]
+        @country = attributes[:country]
+        @city = attributes[:city]
+        @utm_source = attributes[:utm_source]
+        @utm_medium = attributes[:utm_medium]
+        @utm_campaign = attributes[:utm_campaign]
+        @utm_term = attributes[:utm_term]
+        @utm_content = attributes[:utm_content]
+        @referring_domain = attributes[:referring_domain]
+        @search_keyword = attributes[:search_keyword]
+        @started_at = attributes[:started_at] || Time.now
+        @ended_at = attributes[:ended_at]
+        @created_at = attributes[:created_at] || Time.now
+        @updated_at = attributes[:updated_at] || Time.now
+      end
+
+      def to_h
+        {
+          visit_token: visit_token,
+          visitor_token: visitor_token,
+          tenant_id: tenant_id,
+          user_id: user_id,
+          ip: ip,
+          user_agent: user_agent,
+          referrer: referrer,
+          landing_page: landing_page,
+          browser: browser,
+          os: os,
+          device_type: device_type,
+          country: country,
+          city: city,
+          utm_source: utm_source,
+          utm_medium: utm_medium,
+          utm_campaign: utm_campaign,
+          utm_term: utm_term,
+          utm_content: utm_content,
+          referring_domain: referring_domain,
+          search_keyword: search_keyword,
+          started_at: started_at,
+          ended_at: ended_at,
+          created_at: created_at,
+          updated_at: updated_at
+        }.compact
+      end
+
+      def duration_seconds
+        return nil unless ended_at
+        (ended_at - started_at).to_i
+      end
+
+      def active?
+        ended_at.nil?
+      end
+
+      def expired?(inactivity_duration = 30.minutes)
+        return false unless active?
+        (Time.now - started_at) > inactivity_duration
+      end
+
+      def end!
+        @ended_at = Time.now
+        @updated_at = Time.now
+      end
+    end
+  end
+end
+

data/vendor/assets/javascripts/behavior_analytics.js

@@ -0,0 +1,159 @@
+// Behavior Analytics JavaScript Client
+// This file can be included in your Rails application
+// Usage: <%= javascript_include_tag 'behavior_analytics' %>
+
+(function() {
+  var BehaviorAnalytics = {
+    trackerUrl: '/behavior_analytics/track',
+    visitorToken: null,
+    visitToken: null,
+    
+    init: function() {
+      this.loadVisitorToken();
+      this.autoTrack();
+    },
+    
+    loadVisitorToken: function() {
+      var token = this.getCookie('behavior_visitor_token');
+      if (!token) {
+        token = this.generateToken();
+        this.setCookie('behavior_visitor_token', token, 730); // 2 years
+      }
+      this.visitorToken = token;
+    },
+    
+    generateToken: function() {
+      return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        var r = Math.random() * 16 | 0;
+        var v = c == 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+      });
+    },
+    
+    setCookie: function(name, value, days) {
+      var expires = '';
+      if (days) {
+        var date = new Date();
+        date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
+        expires = '; expires=' + date.toUTCString();
+      }
+      document.cookie = name + '=' + (value || '') + expires + '; path=/; SameSite=Lax';
+    },
+    
+    getCookie: function(name) {
+      var nameEQ = name + '=';
+      var ca = document.cookie.split(';');
+      for (var i = 0; i < ca.length; i++) {
+        var c = ca[i];
+        while (c.charAt(0) == ' ') c = c.substring(1, c.length);
+        if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
+      }
+      return null;
+    },
+    
+    track: function(eventName, properties) {
+      var payload = {
+        event_name: eventName,
+        properties: properties || {},
+        visitor_token: this.visitorToken,
+        visit_token: this.visitToken,
+        page: window.location.pathname,
+        referrer: document.referrer,
+        user_agent: navigator.userAgent,
+        timestamp: new Date().toISOString()
+      };
+      
+      this.sendRequest(payload);
+    },
+    
+    trackPageView: function() {
+      this.track('page_view', {
+        path: window.location.pathname,
+        title: document.title,
+        referrer: document.referrer
+      });
+    },
+    
+    trackClick: function(element, properties) {
+      var props = {
+        element: element.tagName.toLowerCase(),
+        id: element.id || null,
+        class: element.className || null,
+        text: element.textContent ? element.textContent.substring(0, 100) : null
+      };
+      
+      if (properties) {
+        Object.assign(props, properties);
+      }
+      
+      this.track('click', props);
+    },
+    
+    autoTrack: function() {
+      var self = this;
+      
+      // Track page view on load
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function() {
+          self.trackPageView();
+        });
+      } else {
+        this.trackPageView();
+      }
+      
+      // Track clicks on elements with data-track attribute
+      document.addEventListener('click', function(e) {
+        var element = e.target;
+        if (element.hasAttribute('data-track')) {
+          var trackValue = element.getAttribute('data-track');
+          var properties = {};
+          
+          if (element.hasAttribute('data-track-properties')) {
+            try {
+              properties = JSON.parse(element.getAttribute('data-track-properties'));
+            } catch (e) {}
+          }
+          
+          self.track(trackValue || 'click', properties);
+        }
+      });
+      
+      // Track form submissions
+      document.addEventListener('submit', function(e) {
+        var form = e.target;
+        if (form.tagName === 'FORM' && form.hasAttribute('data-track')) {
+          var trackValue = form.getAttribute('data-track');
+          self.track(trackValue || 'form_submit', {
+            form_id: form.id || null,
+            form_action: form.action || null
+          });
+        }
+      });
+    },
+    
+    sendRequest: function(payload) {
+      if (navigator.sendBeacon) {
+        var blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
+        navigator.sendBeacon(this.trackerUrl, blob);
+      } else {
+        var xhr = new XMLHttpRequest();
+        xhr.open('POST', this.trackerUrl, true);
+        xhr.setRequestHeader('Content-Type', 'application/json');
+        xhr.send(JSON.stringify(payload));
+      }
+    }
+  };
+  
+  // Initialize on load
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() {
+      BehaviorAnalytics.init();
+    });
+  } else {
+    BehaviorAnalytics.init();
+  }
+  
+  // Expose globally
+  window.BehaviorAnalytics = BehaviorAnalytics;
+})();
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: behavior_analytics
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.2
 platform: ruby
 authors:
 - nerdawey
@@ -84,21 +84,32 @@ files:
 - behavior_analytics.gemspec
 - db/migrate/001_create_behavior_events.rb
 - db/migrate/002_enhance_behavior_events_v2.rb
+- db/migrate/003_create_behavior_visits.rb
+- db/migrate/004_add_visit_fields_to_events.rb
 - lib/behavior_analytics.rb
 - lib/behavior_analytics/analytics/cohorts.rb
 - lib/behavior_analytics/analytics/engine.rb
 - lib/behavior_analytics/analytics/funnels.rb
+- lib/behavior_analytics/analytics/geographic.rb
+- lib/behavior_analytics/analytics/referrer.rb
 - lib/behavior_analytics/analytics/retention.rb
+- lib/behavior_analytics/cleanup/retention_policy.rb
+- lib/behavior_analytics/cleanup/scheduler.rb
 - lib/behavior_analytics/context.rb
 - lib/behavior_analytics/debug/inspector.rb
+- lib/behavior_analytics/detection/device_detector.rb
+- lib/behavior_analytics/detection/geolocation.rb
 - lib/behavior_analytics/event.rb
 - lib/behavior_analytics/export/csv_exporter.rb
 - lib/behavior_analytics/export/json_exporter.rb
+- lib/behavior_analytics/helpers/tracking_helper.rb
 - lib/behavior_analytics/hooks/callback.rb
 - lib/behavior_analytics/hooks/manager.rb
 - lib/behavior_analytics/hooks/webhook.rb
+- lib/behavior_analytics/identification/user_resolver.rb
 - lib/behavior_analytics/integrations/rails.rb
 - lib/behavior_analytics/integrations/rails/middleware.rb
+- lib/behavior_analytics/javascript/client.rb
 - lib/behavior_analytics/jobs/active_event_job.rb
 - lib/behavior_analytics/jobs/delayed_event_job.rb
 - lib/behavior_analytics/jobs/sidekiq_event_job.rb
@@ -123,9 +134,13 @@ files:
 - lib/behavior_analytics/throttling/limiter.rb
 - lib/behavior_analytics/tracker.rb
 - lib/behavior_analytics/version.rb
+- lib/behavior_analytics/visits/auto_creator.rb
+- lib/behavior_analytics/visits/manager.rb
+- lib/behavior_analytics/visits/visit.rb
 - lib/generators/behavior_analytics/install_generator.rb
 - lib/generators/behavior_analytics/templates/create_behavior_events.rb
 - sig/behavior_analytics.rbs
+- vendor/assets/javascripts/behavior_analytics.js
 homepage: https://github.com/nerdawey/behavior_analytics
 licenses:
 - MIT