behavior_analytics 2.2.0 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f432cc493196bc1c00cbdcdbc7d8e2de54271391012d138a20c7920f7126f981
-  data.tar.gz: 0bef407d3e3d30d70449b20071b54cbf43aae1cb099f2f156d22dc1a3e41a359
+  metadata.gz: 658a8852d807dd03e050e0c773ff213459e168dfd37ecb14d707d381ada8362b
+  data.tar.gz: c7398303e1217051c62384c7ac78e6c43dc5da35ed689917d7b5bab99b4f4b41
 SHA512:
-  metadata.gz: 05e3d818e1b1b4e431ba31e379ac7c8d79492219a0cf9504848084f938f3ce41332b4989c658d6a9d748a35d3716b231460712bc331b9f607473d552ab309b7d
-  data.tar.gz: fa8aa9ce4b51f5a8741140803ff4f8d2b37d4843ba6d2c28088b3e1bb390fa1d47fd9e89c59cf57869d8e54168fa76bd265f45b8293dd78fadcfea27736234bb
+  metadata.gz: a795b6a6ca62eebe154b73a7a5b3377e1b305b7c1fce76e8da2acecc4535a69e34fe39914b4491a014929d55121848a06706f0d2c111262f4661453b08b7c4f9
+  data.tar.gz: 237f9c73911e9c42cf1922158e9724f094a32fffee340077046509f3b966495af9e4d1f4bf3db442e4f9ac0ccb8a688927f9bf3db5b099d0be434ff5255bb52d

data/README.md

@@ -1,6 +1,6 @@
 # Behavior Analytics
 
-A comprehensive Ruby gem for tracking user behavior events with multi-tenant support, visit/session management, device detection, geographic analytics, and advanced querying capabilities. Inspired by Ahoy analytics with enterprise-grade features.
+A comprehensive Ruby gem for tracking user behavior events with multi-tenant support, visit/session management, device detection, geographic analytics, and advanced querying capabilities with enterprise-grade features.
 
 ## Features
 
@@ -35,7 +35,7 @@ A comprehensive Ruby gem for tracking user behavior events with multi-tenant sup
 - **Event Streaming**: Real-time event pub/sub system
 
 ### Developer Experience
-- **Simplified API**: Ahoy-inspired simple tracking API with automatic context resolution
+- **Simplified API**: Simple tracking API with automatic context resolution
 - **Rails Integration**: Automatic API call tracking via middleware with selective tracking
 - **Query Interface**: Fluent query builder for filtering events with advanced aggregations
 - **JavaScript Client**: Frontend tracking with automatic page views and click tracking
@@ -117,7 +117,7 @@ BehaviorAnalytics.configure do |config|
     time_in_trial: 0.1
   }
 
-  # Visit/Session Management (Ahoy-inspired features)
+  # Visit/Session Management
   config.track_visits = true                    # Enable visit tracking
   config.visit_duration = 30.minutes            # Visit expires after 30 min of inactivity
   config.track_device_info = true               # Auto-detect device, browser, OS
@@ -167,9 +167,9 @@ Or use the inline script generator:
 
 ## Usage
 
-### Simplified API (Ahoy-Inspired)
+### Simplified API
 
-The gem provides a simplified API similar to Ahoy for easy tracking:
+The gem provides a simplified API for easy tracking:
 
 ```ruby
 # Simple event tracking with automatic context resolution

data/behavior_analytics.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   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, " \
+                     "visit/session management, 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"

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
+