behavior_analytics 2.1.0 → 2.2.0

data/behavior_analytics.gemspec

@@ -8,10 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors = ["nerdawey"]
   spec.email = ["nerdawy@icloud.com"]
 
-  spec.summary = "Track user behavior events with flexible context filtering and comprehensive analytics"
-  spec.description = "A Ruby gem for tracking user behavior events with multi-tenant support, " \
-                     "computing analytics (engagement scores, time-based trends, feature usage), " \
-                     "and supporting API calls, feature usage, and custom events."
+  spec.summary = "Track user behavior events with visit tracking, device detection, and comprehensive analytics"
+  spec.description = "A comprehensive Ruby gem for tracking user behavior events with multi-tenant support, " \
+                     "visit/session management (Ahoy-inspired), device & browser detection, geographic analytics, " \
+                     "referrer tracking, and advanced analytics (engagement scores, funnels, cohorts, retention). " \
+                     "Supports API calls, feature usage, custom events, and JavaScript client-side tracking."
   spec.homepage = "https://github.com/nerdawey/behavior_analytics"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0.0"

data/lib/behavior_analytics/analytics/engine.rb

@@ -13,6 +13,8 @@ module BehaviorAnalytics
         @funnels = nil
         @cohorts = nil
         @retention = nil
+        @geographic = nil
+        @referrer = nil
       end
 
       def event_count(context, options = {})
@@ -139,6 +141,14 @@ module BehaviorAnalytics
         @retention ||= Retention.new(@storage_adapter)
       end
 
+      def geographic
+        @geographic ||= Geographic.new(storage_adapter: @storage_adapter)
+      end
+
+      def referrer
+        @referrer ||= Referrer.new(storage_adapter: @storage_adapter)
+      end
+
       private
 
       def normalize_context(context)

data/lib/behavior_analytics/event.rb

@@ -7,7 +7,8 @@ module BehaviorAnalytics
     EVENT_TYPES = %i[api_call feature_usage custom].freeze
 
     attr_accessor :id, :tenant_id, :user_id, :user_type, :event_name, :event_type,
-                  :metadata, :session_id, :ip, :user_agent, :duration_ms, :created_at
+                  :metadata, :session_id, :ip, :user_agent, :duration_ms, :created_at,
+                  :visit_id, :visitor_id
 
     def initialize(attributes = {})
       @id = attributes[:id] || SecureRandom.uuid
@@ -21,6 +22,8 @@ module BehaviorAnalytics
       @ip = attributes[:ip]
       @user_agent = attributes[:user_agent]
       @duration_ms = attributes[:duration_ms]
+      @visit_id = attributes[:visit_id]
+      @visitor_id = attributes[:visitor_id]
       @created_at = attributes[:created_at] || Time.now
 
       validate!
@@ -39,6 +42,8 @@ module BehaviorAnalytics
         ip: ip,
         user_agent: user_agent,
         duration_ms: duration_ms,
+        visit_id: visit_id,
+        visitor_id: visitor_id,
         created_at: created_at
       }
     end

data/lib/behavior_analytics/integrations/rails.rb

@@ -26,34 +26,6 @@ module BehaviorAnalytics
 
       private
 
-      def track_behavior_analytics
-        start_time = Time.current
-        yield
-      ensure
-        if should_track?
-          context = resolve_tracking_context
-          if context&.valid?
-            duration_ms = ((Time.current - start_time) * 1000).to_i
-
-            behavior_tracker.track_api_call(
-              context: context,
-              method: request.method,
-              path: request.path,
-              status_code: response.status,
-              duration_ms: duration_ms,
-              ip: request.remote_ip,
-              user_agent: request.user_agent,
-              session_id: session.id,
-              metadata: {
-                controller: controller_name,
-                action: action_name,
-                format: request.format.to_s
-              }
-            )
-          end
-        end
-      end
-
       def behavior_tracker
         @behavior_tracker ||= BehaviorAnalytics.create_tracker(
           storage_adapter: BehaviorAnalytics.configuration.storage_adapter
@@ -180,6 +152,25 @@ module BehaviorAnalytics
               end
             end
 
+            # Get or create visit if visit tracking is enabled
+            visit = nil
+            visitor_id = nil
+            if BehaviorAnalytics.configuration.track_visits && visit_manager
+              begin
+                visit = visit_auto_creator.get_or_create_visit(
+                  request: request,
+                  tenant_id: context.tenant_id,
+                  user_id: context.user_id
+                )
+                visitor_id = visit.visitor_token
+                
+                # Set visitor token cookie
+                visit_auto_creator.set_visitor_token_cookie(response, visitor_id) if respond_to?(:response)
+              rescue StandardError => e
+                BehaviorAnalytics.configuration.log_error(e, context: { action: "visit_creation" })
+              end
+            end
+
             behavior_tracker.track_api_call(
               context: context,
               method: request.method,
@@ -189,6 +180,8 @@ module BehaviorAnalytics
               ip: request.remote_ip,
               user_agent: request.user_agent,
               session_id: session.id,
+              visit_id: visit&.visit_token,
+              visitor_id: visitor_id,
               metadata: {
                 controller: controller_name,
                 action: action_name,
@@ -201,6 +194,30 @@ module BehaviorAnalytics
         end
       end
 
+      def visit_manager
+        return nil unless BehaviorAnalytics.configuration.track_visits
+        @visit_manager ||= begin
+          device_detector = if BehaviorAnalytics.configuration.track_device_info
+            Detection::DeviceDetector.new(strategy: BehaviorAnalytics.configuration.device_detector)
+          end
+          
+          geolocation = if BehaviorAnalytics.configuration.track_geolocation
+            Detection::Geolocation.new(strategy: :geocoder)
+          end
+          
+          Visits::Manager.new(
+            storage_adapter: @behavior_tracker&.storage_adapter || BehaviorAnalytics.configuration.storage_adapter,
+            visit_duration: BehaviorAnalytics.configuration.visit_duration || 30.minutes,
+            device_detector: device_detector,
+            geolocation: geolocation
+          )
+        end
+      end
+
+      def visit_auto_creator
+        @visit_auto_creator ||= Visits::AutoCreator.new(manager: visit_manager)
+      end
+
       def log_slow_query(duration_ms, path)
         if defined?(Rails) && Rails.logger
           Rails.logger.warn("BehaviorAnalytics: Slow query detected: #{path} took #{duration_ms}ms")

data/lib/behavior_analytics/storage/active_record_adapter.rb

@@ -27,6 +27,8 @@ module BehaviorAnalytics
             ip: event_hash[:ip],
             user_agent: event_hash[:user_agent],
             duration_ms: event_hash[:duration_ms],
+            visit_id: event_hash[:visit_id],
+            visitor_id: event_hash[:visitor_id],
             created_at: event_hash[:created_at] || (defined?(Time.current) ? Time.current : Time.now)
           }
         end
@@ -36,6 +38,69 @@ module BehaviorAnalytics
         raise Error, "Failed to save events: #{e.message}"
       end
 
+      def save_visit(visit_data)
+        return unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visit_hash = visit_data.is_a?(Hash) ? visit_data : visit_data.to_h
+        
+        visit = visit_model.find_or_initialize_by(visit_token: visit_hash[:visit_token])
+        visit.assign_attributes(visit_hash.except(:visit_token))
+        visit.save!
+      rescue StandardError => e
+        raise Error, "Failed to save visit: #{e.message}"
+      end
+
+      def find_active_visit(visitor_token, user_id = nil, visit_duration = 30.minutes)
+        return nil unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        query = visit_model.where(visitor_token: visitor_token)
+                          .where(ended_at: nil)
+                          .where("started_at > ?", visit_duration.ago)
+        
+        query = query.where(user_id: user_id) if user_id
+        visit = query.order(started_at: :desc).first
+        
+        visit&.attributes&.symbolize_keys
+      end
+
+      def find_visit_by_token(visit_token)
+        return nil unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visit = visit_model.find_by(visit_token: visit_token)
+        visit&.attributes&.symbolize_keys
+      end
+
+      def link_user_to_visits(visitor_token, user_id)
+        return unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visit_model.where(visitor_token: visitor_token, user_id: nil)
+                   .update_all(user_id: user_id, updated_at: Time.current)
+      end
+
+      def find_visits_by_user(user_id, limit: 100)
+        return [] unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visits = visit_model.where(user_id: user_id)
+                           .order(started_at: :desc)
+                           .limit(limit)
+        visits.map(&:attributes).map(&:symbolize_keys)
+      end
+
+      def find_visits_by_visitor(visitor_token, limit: 100)
+        return [] unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visits = visit_model.where(visitor_token: visitor_token)
+                           .order(started_at: :desc)
+                           .limit(limit)
+        visits.map(&:attributes).map(&:symbolize_keys)
+      end
+
       def events_for_context(context, options = {})
         context.validate!
 
@@ -142,6 +207,29 @@ module BehaviorAnalytics
         @model_class.where("created_at < ?", before_date).delete_all
       end
 
+      def delete_old_visits(before_date)
+        return 0 unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        visit_model.where("started_at < ?", before_date).delete_all
+      end
+
+      def query_visits(context, options = {})
+        return [] unless defined?(BehaviorAnalyticsVisit)
+        
+        visit_model = BehaviorAnalyticsVisit
+        query = visit_model.all
+        
+        query = query.where(tenant_id: context.tenant_id) if context.has_tenant?
+        query = query.where(user_id: context.user_id) if context.has_user?
+        
+        query = query.where("started_at >= ?", options[:since]) if options[:since]
+        query = query.where("started_at <= ?", options[:until]) if options[:until]
+        query = query.limit(options[:limit]) if options[:limit]
+        
+        query.map(&:attributes).map(&:symbolize_keys)
+      end
+
       def event_count(context, options = {})
         context.validate!
         query = build_base_query(context, options)

data/lib/behavior_analytics/tracker.rb

@@ -21,6 +21,7 @@ module BehaviorAnalytics
       @schema_validator = options[:schema_validator] || BehaviorAnalytics.configuration.schema_validator
       @metrics = options[:metrics] || BehaviorAnalytics.configuration.metrics || Observability::Metrics.new
       @tracer = options[:tracer] || BehaviorAnalytics.configuration.tracer
+      @visit_manager = options[:visit_manager]
 
       @buffer = []
       @mutex = Mutex.new
@@ -64,7 +65,9 @@ module BehaviorAnalytics
         session_id: options[:session_id],
         ip: options[:ip],
         user_agent: options[:user_agent],
-        duration_ms: options[:duration_ms]
+        duration_ms: options[:duration_ms],
+        visit_id: options[:visit_id],
+        visitor_id: options[:visitor_id]
       }
 
       # Validate schema if validator is configured
@@ -76,17 +79,6 @@ module BehaviorAnalytics
       end
 
       event = Event.new(event_data)
-        tenant_id: context.tenant_id,
-        user_id: context.user_id,
-        user_type: context.user_type,
-        event_name: event_name,
-        event_type: event_type,
-        metadata: metadata.merge(context.filters),
-        session_id: options[:session_id],
-        ip: options[:ip],
-        user_agent: options[:user_agent],
-        duration_ms: options[:duration_ms]
-      )
 
       # Execute before_track hooks
       begin

data/lib/behavior_analytics/version.rb

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

data/lib/behavior_analytics.rb

@@ -27,6 +27,11 @@ require_relative "behavior_analytics/analytics/engine"
 require_relative "behavior_analytics/analytics/funnels"
 require_relative "behavior_analytics/analytics/cohorts"
 require_relative "behavior_analytics/analytics/retention"
+require_relative "behavior_analytics/analytics/geographic"
+require_relative "behavior_analytics/analytics/referrer"
+require_relative "behavior_analytics/identification/user_resolver"
+require_relative "behavior_analytics/cleanup/retention_policy"
+require_relative "behavior_analytics/cleanup/scheduler"
 require_relative "behavior_analytics/hooks/manager"
 require_relative "behavior_analytics/hooks/webhook"
 require_relative "behavior_analytics/hooks/callback"
@@ -46,6 +51,12 @@ require_relative "behavior_analytics/processors/async_processor"
 require_relative "behavior_analytics/processors/background_job_processor"
 require_relative "behavior_analytics/streaming/event_stream"
 
+require_relative "behavior_analytics/visits/visit"
+require_relative "behavior_analytics/visits/manager"
+require_relative "behavior_analytics/visits/auto_creator"
+require_relative "behavior_analytics/detection/device_detector"
+require_relative "behavior_analytics/detection/geolocation"
+
 begin
   require_relative "behavior_analytics/integrations/rails"
 rescue LoadError
@@ -95,7 +106,9 @@ module BehaviorAnalytics
                   :hooks_manager, :raise_on_hook_error, :sampling_strategy, :rate_limiter,
                   :schema_validator, :schema_registry, :tracking_whitelist, :tracking_blacklist,
                   :skip_bots, :controller_action_filters, :slow_query_threshold, :track_middleware_requests,
-                  :metrics, :tracer, :debug_mode, :logger, :default_tenant_id
+                  :metrics, :tracer, :debug_mode, :logger, :default_tenant_id,
+                  :track_visits, :visit_duration, :track_geolocation, :track_device_info,
+                  :visit_retention_days, :event_retention_days, :device_detector
 
     def initialize
       @batch_size = 100
@@ -124,6 +137,13 @@ module BehaviorAnalytics
       @debug_mode = @environment == "development"
       @logger = nil
       @default_tenant_id = "default" # Default tenant for single-tenant systems
+      @track_visits = false
+      @visit_duration = 30.minutes
+      @track_geolocation = false
+      @track_device_info = false
+      @visit_retention_days = 90
+      @event_retention_days = 365
+      @device_detector = :browser
     end
 
     def debug(message, context: nil)
@@ -184,5 +204,53 @@ module BehaviorAnalytics
     def create_tracker(options = {})
       Tracker.new(options)
     end
+
+    # Simplified API methods (Ahoy-inspired)
+    def track(event_name, properties: {}, event_type: :custom, context: nil, **options)
+      # Resolve context automatically if not provided
+      context ||= resolve_default_context
+      
+      tracker = create_tracker
+      tracker.track(
+        context: context,
+        event_name: event_name,
+        event_type: event_type,
+        metadata: properties,
+        **options
+      )
+    end
+
+    def track_page_view(path:, properties: {}, **options)
+      track("page_view", properties: { path: path }.merge(properties), **options)
+    end
+
+    def track_click(element:, properties: {}, **options)
+      track("click", properties: { element: element }.merge(properties), **options)
+    end
+
+    def track_conversion(conversion_name:, value: nil, properties: {}, **options)
+      props = { conversion_name: conversion_name }
+      props[:value] = value if value
+      track("conversion", properties: props.merge(properties), **options)
+    end
+
+    def tracker
+      @tracker ||= create_tracker
+    end
+
+    private
+
+    def resolve_default_context
+      # Try to resolve from Rails if available
+      if defined?(Rails) && defined?(ActionController::Base)
+        # This will be called in controller context
+        # For now, return a basic context
+        Context.new(tenant_id: configuration.default_tenant_id)
+      else
+        Context.new(tenant_id: configuration.default_tenant_id)
+      end
+    end
   end
 end
+
+require_relative "behavior_analytics/helpers/tracking_helper"

data/lib/generators/behavior_analytics/templates/create_behavior_events.rb

@@ -3,7 +3,7 @@
 class CreateBehaviorEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :behavior_events do |t|
-      t.string :tenant_id, null: false
+      t.string :tenant_id  # Nullable to support single-tenant and API-only tracking
       t.string :user_id
       t.string :user_type
       t.string :event_name, null: false
@@ -16,7 +16,7 @@ class CreateBehaviorEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration
       t.datetime :created_at, null: false
     end
 
-    add_index :behavior_events, :tenant_id
+    add_index :behavior_events, :tenant_id  # Index even if nullable for multi-tenant queries
     add_index :behavior_events, :user_id
     add_index :behavior_events, :user_type
     add_index :behavior_events, :event_name

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: behavior_analytics
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - nerdawey
@@ -66,9 +66,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
-description: A Ruby gem for tracking user behavior events with multi-tenant support,
-  computing analytics (engagement scores, time-based trends, feature usage), and supporting
-  API calls, feature usage, and custom events.
+description: A comprehensive Ruby gem for tracking user behavior events with multi-tenant
+  support, visit/session management (Ahoy-inspired), device & browser detection, geographic
+  analytics, referrer tracking, and advanced analytics (engagement scores, funnels,
+  cohorts, retention). Supports API calls, feature usage, custom events, and JavaScript
+  client-side tracking.
 email:
 - nerdawy@icloud.com
 executables: []
@@ -149,6 +151,6 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
-summary: Track user behavior events with flexible context filtering and comprehensive
+summary: Track user behavior events with visit tracking, device detection, and comprehensive
   analytics
 test_files: []