behavior_analytics 2.1.0 → 2.2.0

data/README.md

@@ -1,21 +1,45 @@
 # Behavior Analytics
 
-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.
+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.
 
 ## Features
 
+### Core Features
 - **Flexible Context Tracking**: Track events with multi-tenant support, user types, and custom filters
 - **Event Buffering**: Efficient batch processing with configurable buffer size and flush intervals
+- **Visit/Session Management**: Automatic visit tracking with session management, visitor identification, and visit analytics
+- **Device & Browser Detection**: Automatic device, browser, and OS detection from user agents
+- **Geographic Analytics**: Country, city, and region tracking from IP addresses
+- **Referrer Analytics**: UTM parameter tracking, source analysis, and search keyword extraction
+
+### Analytics & Insights
 - **Comprehensive Analytics**: 
   - Event counts and aggregations
   - Engagement scoring with customizable weights
   - Time-based analytics (hourly, daily, weekly, monthly)
   - Feature usage statistics
-- **Storage Adapters**: 
+  - Funnel analysis
+  - Cohort analysis
+  - Retention tracking
+- **Geographic Analytics**: Country/city breakdowns, device/browser statistics
+- **Referrer Analytics**: Traffic source analysis, UTM campaign tracking, search keyword insights
+
+### Storage & Performance
+- **Multiple Storage Adapters**: 
   - ActiveRecord adapter for production use
   - In-memory adapter for testing
-- **Rails Integration**: Automatic API call tracking via middleware
-- **Query Interface**: Fluent query builder for filtering events
+  - Redis adapter for high-throughput scenarios
+  - Elasticsearch adapter for advanced search
+  - Kafka adapter for event streaming
+- **Async Processing**: Background job support (Sidekiq, DelayedJob, ActiveJob)
+- **Event Streaming**: Real-time event pub/sub system
+
+### Developer Experience
+- **Simplified API**: Ahoy-inspired 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
+- **Data Retention**: Automatic cleanup policies for visits and events
 
 ## Installation
 
@@ -46,16 +70,21 @@ rails generate behavior_analytics:install
 ```
 
 This will:
-- Create a migration for the `behavior_events` table
+- Create migrations for the `behavior_events` and `behavior_visits` tables
 - Create an initializer at `config/initializers/behavior_analytics.rb`
-- Create a model at `app/models/behavior_analytics_event.rb`
+- Create models at `app/models/behavior_analytics_event.rb` and `app/models/behavior_analytics_visit.rb`
 
-### 2. Run the migration
+### 2. Run the migrations
 
 ```bash
 rails db:migrate
 ```
 
+This will create:
+- `behavior_events` table for event tracking
+- `behavior_visits` table for visit/session tracking
+- Indexes for optimal query performance
+
 ### 3. Configure the initializer
 
 Edit `config/initializers/behavior_analytics.rb`:
@@ -87,6 +116,24 @@ BehaviorAnalytics.configure do |config|
     feature_diversity: 0.2,
     time_in_trial: 0.1
   }
+
+  # Visit/Session Management (Ahoy-inspired features)
+  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
+  config.track_geolocation = true               # Auto-detect country/city from IP
+  config.device_detector = :simple              # :simple, :browser, or :user_agent_parser
+
+  # Data Retention
+  config.visit_retention_days = 90              # Keep visits for 90 days
+  config.event_retention_days = 365            # Keep events for 1 year
+
+  # Single-tenant support
+  config.default_tenant_id = "global"          # For non-multi-tenant systems
+
+  # Optional: Advanced features
+  config.use_async = false                      # Enable async processing
+  config.debug_mode = Rails.env.development?   # Enable debug logging
 end
 ```
 
@@ -98,8 +145,175 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+### 5. (Optional) Add JavaScript Client
+
+Include the JavaScript client in your layout:
+
+```erb
+<!-- app/views/layouts/application.html.erb -->
+<%= javascript_include_tag 'behavior_analytics' %>
+```
+
+Or use the inline script generator:
+
+```erb
+<script>
+  <%= BehaviorAnalytics::Javascript::Client.generate_script(
+    tracker_url: behavior_analytics_track_path,
+    auto_track: true
+  ).html_safe %>
+</script>
+```
+
 ## Usage
 
+### Simplified API (Ahoy-Inspired)
+
+The gem provides a simplified API similar to Ahoy for easy tracking:
+
+```ruby
+# Simple event tracking with automatic context resolution
+BehaviorAnalytics.track("button_click", properties: { button: "signup" })
+
+# Page view tracking
+BehaviorAnalytics.track_page_view(path: "/dashboard")
+
+# Click tracking
+BehaviorAnalytics.track_click(element: "signup_button", properties: { location: "header" })
+
+# Conversion tracking
+BehaviorAnalytics.track_conversion(conversion_name: "signup", value: 99.99)
+
+# Or use the helper methods in controllers
+class ApplicationController < ActionController::Base
+  include BehaviorAnalytics::Helpers::TrackingHelper
+
+  def create
+    # ... create logic ...
+    track_event("project_created", properties: { project_id: @project.id })
+  end
+end
+```
+
+### Visit/Session Management
+
+Visits are automatically created and tracked when visit tracking is enabled:
+
+```ruby
+# Visits are automatically created on first request
+# You can access the current visit in your controllers:
+
+class ApplicationController < ActionController::Base
+  include BehaviorAnalytics::Integrations::Rails
+
+  def current_visit
+    @current_visit ||= visit_manager&.find_or_create_visit(
+      visitor_token: visit_auto_creator.get_or_create_visitor_token(request),
+      tenant_id: current_tenant&.id,
+      user_id: current_user&.id,
+      ip: request.ip,
+      user_agent: request.user_agent,
+      referrer: request.referer,
+      landing_page: request.path
+    )
+  end
+end
+
+# Query visits
+tracker = BehaviorAnalytics.create_tracker
+visit_manager = BehaviorAnalytics::Visits::Manager.new(
+  storage_adapter: tracker.storage_adapter
+)
+
+# Get user's visits
+user_visits = visit_manager.find_visits_by_user(user_id, limit: 100)
+
+# Get visitor's visits (anonymous)
+visitor_visits = visit_manager.find_visits_by_visitor(visitor_token, limit: 100)
+
+# Link anonymous visits to user on login
+user_resolver = BehaviorAnalytics::Identification::UserResolver.new(
+  visit_manager: visit_manager
+)
+user_resolver.identify_user(user_id, visitor_token: visitor_token)
+```
+
+### Device & Browser Detection
+
+Device information is automatically detected and stored in visits:
+
+```ruby
+# Device detection happens automatically when track_device_info is enabled
+# Visit will include:
+# - browser: "Chrome", "Safari", "Firefox", etc.
+# - os: "iOS", "Android", "Windows", "Mac OS", etc.
+# - device_type: "mobile", "tablet", "desktop"
+
+# You can also manually detect device info:
+detector = BehaviorAnalytics::Detection::DeviceDetector.new(strategy: :simple)
+device_info = detector.detect(request.user_agent)
+# => { browser: "Chrome", os: "Mac OS", device_type: "desktop" }
+```
+
+### Geographic Analytics
+
+Geographic information is automatically detected from IP addresses:
+
+```ruby
+# Geolocation happens automatically when track_geolocation is enabled
+# Visit will include:
+# - country: "United States"
+# - city: "San Francisco"
+# - country_code: "US"
+
+# Query geographic analytics
+analytics = tracker.analytics
+
+# Country breakdown
+countries = analytics.geographic.country_breakdown(context)
+# => [{ country: "United States", count: 150 }, { country: "Canada", count: 50 }]
+
+# City breakdown
+cities = analytics.geographic.city_breakdown(context)
+# => [{ city: "San Francisco", count: 75 }, { city: "New York", count: 50 }]
+
+# Device breakdown
+devices = analytics.geographic.device_breakdown(context)
+# => [{ device: "desktop", count: 100 }, { device: "mobile", count: 50 }]
+
+# Browser breakdown
+browsers = analytics.geographic.browser_breakdown(context)
+# => [{ browser: "Chrome", count: 120 }, { browser: "Safari", count: 30 }]
+```
+
+### Referrer Analytics
+
+Track traffic sources, UTM parameters, and search keywords:
+
+```ruby
+analytics = tracker.analytics
+
+# Traffic source breakdown
+sources = analytics.referrer.source_breakdown(context)
+# => [{ source: "google", count: 100 }, { source: "direct", count: 50 }]
+
+# UTM source breakdown
+utm_sources = analytics.referrer.utm_source_breakdown(context)
+# => [{ utm_source: "newsletter", count: 75 }, { utm_source: "social", count: 25 }]
+
+# UTM campaign breakdown
+campaigns = analytics.referrer.utm_campaign_breakdown(context)
+# => [{ utm_campaign: "summer_sale", count: 50 }, { utm_campaign: "winter_promo", count: 30 }]
+
+# Search keyword breakdown
+keywords = analytics.referrer.search_keyword_breakdown(context)
+# => [{ keyword: "ruby gem", count: 20 }, { keyword: "analytics", count: 15 }]
+
+# Referring domain breakdown
+domains = analytics.referrer.referring_domain_breakdown(context)
+# => [{ domain: "google.com", count: 100 }, { domain: "twitter.com", count: 25 }]
+```
+
 ### Supported Business Cases
 
 The gem is flexible and supports different business scenarios:
@@ -243,6 +457,66 @@ feature_stats = analytics.feature_usage_stats(context)
 # => { "projects" => 25, "search" => 10, ... }
 
 top_features = analytics.top_features(context, limit: 10)
+
+# Funnel analysis
+funnel = analytics.funnels.create(
+  name: "signup_funnel",
+  steps: ["page_view", "signup_form", "signup_submit", "email_verified"]
+)
+conversion_rate = funnel.conversion_rate(context)
+
+# Cohort analysis
+cohort = analytics.cohorts.create(
+  name: "signup_cohort",
+  event_name: "signup",
+  period: :monthly
+)
+cohort_data = cohort.analyze(context)
+
+# Retention analysis
+retention = analytics.retention.calculate(
+  context: context,
+  event_name: "login",
+  period: :weekly
+)
+```
+
+### Data Retention & Cleanup
+
+Automatically clean up old visits and events:
+
+```ruby
+# Configure retention policy
+retention_policy = BehaviorAnalytics::Cleanup::RetentionPolicy.new(
+  visit_retention_days: 90,
+  event_retention_days: 365
+)
+
+# Create scheduler
+scheduler = BehaviorAnalytics::Cleanup::Scheduler.new(
+  storage_adapter: tracker.storage_adapter,
+  retention_policy: retention_policy
+)
+
+# Cleanup old data
+results = scheduler.cleanup_all
+# => { visits: 1500, events: 50000 }
+
+# Or cleanup separately
+deleted_visits = scheduler.cleanup_visits
+deleted_events = scheduler.cleanup_events
+
+# Schedule cleanup job (e.g., in a cron job or scheduled task)
+# config/schedule.rb (whenever gem)
+every 1.day, at: '2:00 am' do
+  runner "BehaviorAnalytics::Cleanup::Scheduler.new(
+    storage_adapter: BehaviorAnalytics.configuration.storage_adapter,
+    retention_policy: BehaviorAnalytics::Cleanup::RetentionPolicy.new(
+      visit_retention_days: BehaviorAnalytics.configuration.visit_retention_days,
+      event_retention_days: BehaviorAnalytics.configuration.event_retention_days
+    )
+  ).cleanup_all"
+end
 ```
 
 ### Query Interface
@@ -264,6 +538,70 @@ count = query
   .for_tenant("org_123")
   .with_event_name("project_created")
   .count
+
+# Advanced filtering
+events = query
+  .with_metadata(key: "feature", value: "advanced_search")
+  .with_path("/api/search")
+  .with_method("POST")
+  .with_status_code(200)
+  .group_by(:user_id)
+  .aggregate(field: :duration_ms, function: :avg)
+  .execute
+
+# Visit-based queries
+visit_events = query
+  .for_visit(visit_token)
+  .with_event_type(:custom)
+  .execute
+```
+
+### JavaScript Client
+
+The JavaScript client provides automatic frontend tracking:
+
+```javascript
+// Automatic tracking (enabled by default)
+// - Page views on load
+// - Clicks on elements with data-track attribute
+// - Form submissions with data-track attribute
+
+// Manual tracking
+BehaviorAnalytics.track("button_click", { button: "signup" });
+BehaviorAnalytics.trackPageView();
+BehaviorAnalytics.trackClick(element, { location: "header" });
+
+// HTML attributes for automatic tracking
+<button data-track="signup_click" data-track-properties='{"plan": "premium"}'>
+  Sign Up
+</button>
+
+<form data-track="newsletter_signup">
+  <!-- form fields -->
+</form>
+```
+
+### User Identification & Visitor Tracking
+
+Track anonymous visitors and merge with user accounts:
+
+```ruby
+# Identify user on login (merges anonymous visits)
+user_resolver = BehaviorAnalytics::Identification::UserResolver.new(
+  visit_manager: visit_manager
+)
+
+# On user login
+user_resolver.identify_user(
+  user_id: current_user.id,
+  visitor_token: cookies[:behavior_visitor_token]
+)
+
+# Get all visits for a user (including anonymous visits before login)
+user_visits = user_resolver.get_user_visits(user_id)
+
+# Get visits for anonymous visitor
+visitor_visits = user_resolver.get_visitor_visits(visitor_token)
 ```
 
 ### Custom Storage Adapter
@@ -288,6 +626,8 @@ tracker = BehaviorAnalytics.create_tracker(
 
 ## Configuration Options
 
+### Core Configuration
+
 - `storage_adapter`: Storage adapter instance (required)
 - `batch_size`: Number of events to buffer before flushing (default: 100)
 - `flush_interval`: Seconds between automatic flushes (default: 300)
@@ -295,12 +635,71 @@ tracker = BehaviorAnalytics.create_tracker(
 - `scoring_weights`: Hash of weights for engagement scoring
 - `default_tenant_id`: Default tenant ID for single-tenant systems (default: "default")
 
+### Visit/Session Management
+
+- `track_visits`: Enable visit tracking (default: false)
+- `visit_duration`: Visit expiration time after inactivity (default: 30.minutes)
+- `track_device_info`: Enable automatic device/browser detection (default: false)
+- `track_geolocation`: Enable automatic geographic detection from IP (default: false)
+- `device_detector`: Device detection strategy - `:simple`, `:browser`, or `:user_agent_parser` (default: `:simple`)
+
+### Data Retention
+
+- `visit_retention_days`: Days to keep visits before cleanup (default: 90)
+- `event_retention_days`: Days to keep events before cleanup (default: 365)
+
+### Advanced Features
+
+- `use_async`: Enable async event processing (default: false)
+- `async_processor`: Async processor instance (Sidekiq, DelayedJob, ActiveJob)
+- `event_stream`: Event streaming instance for pub/sub
+- `hooks_manager`: Event hooks manager for lifecycle callbacks
+- `sampling_strategy`: Event sampling strategy
+- `rate_limiter`: Rate limiting configuration
+- `schema_validator`: Event schema validator
+- `metrics`: Metrics collection instance
+- `tracer`: Distributed tracing instance
+- `debug_mode`: Enable debug logging (default: development mode)
+- `logger`: Custom logger instance
+
+### Rails Integration
+
+- `tracking_whitelist`: Array of path patterns to whitelist (nil = track all)
+- `tracking_blacklist`: Array of path patterns to blacklist (default: [])
+- `skip_bots`: Skip tracking for bot user agents (default: true)
+- `controller_action_filters`: Hash of controllers/actions to filter
+- `slow_query_threshold`: Log slow queries above threshold (ms)
+- `track_middleware_requests`: Track requests via middleware (default: false)
+
 ## Event Types
 
-- `:api_call` - HTTP API requests
+- `:api_call` - HTTP API requests (automatically tracked via Rails integration)
 - `:feature_usage` - Feature usage events
 - `:custom` - Custom business events
 
+## Visit Model
+
+Visits track user sessions and include:
+
+- `visit_token`: Unique identifier for the visit
+- `visitor_token`: Anonymous visitor identifier (persists across visits)
+- `tenant_id`: Multi-tenant identifier
+- `user_id`: User identifier (set when user logs in)
+- `ip`: IP address
+- `user_agent`: Browser user agent string
+- `referrer`: HTTP referrer
+- `landing_page`: First page visited in session
+- `browser`: Detected browser (Chrome, Safari, Firefox, etc.)
+- `os`: Detected operating system (iOS, Android, Windows, etc.)
+- `device_type`: Device type (mobile, tablet, desktop)
+- `country`: Country from IP geolocation
+- `city`: City from IP geolocation
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`: UTM parameters
+- `referring_domain`: Extracted referring domain
+- `search_keyword`: Extracted search keyword from search engines
+- `started_at`: Visit start time
+- `ended_at`: Visit end time (null for active visits)
+
 ## Context
 
 The `Context` class encapsulates tracking context and is flexible to support different business cases:
@@ -372,16 +771,470 @@ context = BehaviorAnalytics::Context.new(
 tracker.track(context: context, event_name: "page_view")
 ```
 
+## Advanced Usage
+
+### Async Processing
+
+Process events asynchronously using background jobs:
+
+```ruby
+# Configure async processor
+BehaviorAnalytics.configure do |config|
+  config.use_async = true
+  config.async_processor = BehaviorAnalytics::Processors::BackgroundJobProcessor.new(
+    job_class: BehaviorAnalytics::Jobs::ActiveEventJob
+  )
+end
+
+# Events will be processed in background
+tracker.track(context: context, event_name: "event")
+```
+
+### Event Hooks
+
+Execute callbacks on event lifecycle:
+
+```ruby
+BehaviorAnalytics.configuration.hooks_manager.register_before_track do |event, context|
+  # Modify event before tracking
+  event[:metadata][:custom_field] = "value"
+end
+
+BehaviorAnalytics.configuration.hooks_manager.register_after_track do |event, context|
+  # Execute after tracking
+  NotificationService.notify(event)
+end
+```
+
+### Event Sampling
+
+Sample events to reduce storage:
+
+```ruby
+sampling_strategy = BehaviorAnalytics::Sampling::Strategy.new(
+  sample_rate: 0.1  # Sample 10% of events
+)
+BehaviorAnalytics.configuration.sampling_strategy = sampling_strategy
+```
+
+### Rate Limiting
+
+Limit events per context:
+
+```ruby
+rate_limiter = BehaviorAnalytics::Throttling::Limiter.new(
+  max_events_per_minute: 100
+)
+BehaviorAnalytics.configuration.rate_limiter = rate_limiter
+```
+
+### Event Schema Validation
+
+Validate events against JSON schemas:
+
+```ruby
+schema = BehaviorAnalytics::Schema::Definition.new(
+  event_name: "signup",
+  schema: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+      plan: { type: "string", enum: ["basic", "premium"] }
+    },
+    required: ["email"]
+  }
+)
+
+validator = BehaviorAnalytics::Schema::Validator.new
+validator.register_schema(schema)
+BehaviorAnalytics.configuration.schema_validator = validator
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+v2 is backward compatible with v1. Existing code will continue to work:
+
+```ruby
+# v1 code still works
+tracker.track(context: context, event_name: "event")
+
+# New v2 features are opt-in
+BehaviorAnalytics.configure do |config|
+  config.track_visits = true  # Enable new features
+end
+```
+
+### Enabling Visit Tracking
+
+1. Run migrations:
+```bash
+rails db:migrate
+```
+
+2. Enable in configuration:
+```ruby
+BehaviorAnalytics.configure do |config|
+  config.track_visits = true
+  config.track_device_info = true
+  config.track_geolocation = true
+end
+```
+
+3. Visits will be automatically created on requests
+
+### Migrating Existing Events
+
+If you have existing events and want to link them to visits:
+
+```ruby
+# Create visits for existing events (one-time migration)
+BehaviorAnalyticsEvent.find_each do |event|
+  visit = visit_manager.find_or_create_visit(
+    visitor_token: generate_visitor_token_for_event(event),
+    tenant_id: event.tenant_id,
+    user_id: event.user_id,
+    ip: event.ip,
+    user_agent: event.user_agent
+  )
+  event.update(visit_id: visit.visit_token, visitor_id: visit.visitor_token)
+end
+```
+
+## Performance Considerations
+
+### Database Indexes
+
+The migrations create indexes for optimal query performance. For high-volume applications, consider:
+
+- Additional composite indexes based on your query patterns
+- Partitioning large tables by date
+- Archiving old data to separate tables
+
+### Batch Processing
+
+Configure appropriate batch sizes based on your volume:
+
+```ruby
+# High volume
+config.batch_size = 500
+config.flush_interval = 60  # 1 minute
+
+# Low volume
+config.batch_size = 50
+config.flush_interval = 600  # 10 minutes
+```
+
+### Async Processing
+
+For high-throughput scenarios, use async processing:
+
+```ruby
+config.use_async = true
+config.async_processor = BehaviorAnalytics::Processors::BackgroundJobProcessor.new(
+  job_class: BehaviorAnalytics::Jobs::SidekiqEventJob
+)
+```
+
+## Troubleshooting
+
+### Visits Not Being Created
+
+1. Check that `track_visits` is enabled:
+```ruby
+BehaviorAnalytics.configuration.track_visits # => true
+```
+
+2. Verify migrations are run:
+```bash
+rails db:migrate:status
+```
+
+3. Check Rails integration is included:
+```ruby
+class ApplicationController < ActionController::Base
+  include BehaviorAnalytics::Integrations::Rails
+end
+```
+
+### Device Detection Not Working
+
+1. Ensure `track_device_info` is enabled
+2. Check user agent is being passed:
+```ruby
+request.user_agent  # Should not be nil
+```
+
+3. For better detection, use a gem:
+```ruby
+# Gemfile
+gem 'browser'  # or 'user_agent_parser'
+
+# config
+config.device_detector = :browser
+```
+
+### Geolocation Not Working
+
+1. Ensure `track_geolocation` is enabled
+2. Install geocoding gem:
+```ruby
+# Gemfile
+gem 'geocoder'
+
+# Will automatically use Geocoder for IP lookup
+```
+
+3. For production, consider MaxMind GeoIP2 database
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Building the Gem
+
+```bash
+gem build behavior_analytics.gemspec
+```
+
+### Publishing
+
+```bash
+gem push behavior_analytics-x.x.x.gem
+```
+
+## Complete Example
+
+Here's a complete example showing all features:
+
+```ruby
+# config/initializers/behavior_analytics.rb
+BehaviorAnalytics.configure do |config|
+  config.storage_adapter = BehaviorAnalytics::Storage::ActiveRecordAdapter.new(
+    model_class: BehaviorAnalyticsEvent
+  )
+  
+  # Visit tracking
+  config.track_visits = true
+  config.visit_duration = 30.minutes
+  config.track_device_info = true
+  config.track_geolocation = true
+  
+  # Data retention
+  config.visit_retention_days = 90
+  config.event_retention_days = 365
+  
+  # Single-tenant
+  config.default_tenant_id = "my_app"
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include BehaviorAnalytics::Integrations::Rails
+  include BehaviorAnalytics::Helpers::TrackingHelper
+  
+  private
+  
+  def identify_user_after_login
+    if user_signed_in?
+      user_resolver = BehaviorAnalytics::Identification::UserResolver.new(
+        visit_manager: visit_manager
+      )
+      user_resolver.identify_user(
+        current_user.id,
+        visitor_token: cookies[:behavior_visitor_token]
+      )
+    end
+  end
+end
+
+# app/controllers/projects_controller.rb
+class ProjectsController < ApplicationController
+  def create
+    @project = Project.create(project_params)
+    
+    # Track with simplified API
+    track_event("project_created", properties: {
+      project_id: @project.id,
+      project_name: @project.name
+    })
+    
+    redirect_to @project
+  end
+  
+  def show
+    @project = Project.find(params[:id])
+    
+    # Track page view
+    track_page_view(path: request.path)
+  end
+end
+
+# app/jobs/cleanup_job.rb
+class CleanupJob < ApplicationJob
+  def perform
+    retention_policy = BehaviorAnalytics::Cleanup::RetentionPolicy.new(
+      visit_retention_days: BehaviorAnalytics.configuration.visit_retention_days,
+      event_retention_days: BehaviorAnalytics.configuration.event_retention_days
+    )
+    
+    scheduler = BehaviorAnalytics::Cleanup::Scheduler.new(
+      storage_adapter: BehaviorAnalytics.configuration.storage_adapter,
+      retention_policy: retention_policy
+    )
+    
+    scheduler.cleanup_all
+  end
+end
+
+# Analytics dashboard
+class AnalyticsController < ApplicationController
+  def index
+    tracker = BehaviorAnalytics.create_tracker
+    context = BehaviorAnalytics::Context.new(
+      tenant_id: current_tenant.id
+    )
+    
+    @analytics = {
+      event_count: tracker.analytics.event_count(context, since: 7.days.ago),
+      unique_users: tracker.analytics.unique_users(context),
+      engagement_score: tracker.analytics.engagement_score(context),
+      daily_activity: tracker.analytics.daily_activity(context),
+      top_features: tracker.analytics.top_features(context, limit: 10),
+      countries: tracker.analytics.geographic.country_breakdown(context),
+      sources: tracker.analytics.referrer.source_breakdown(context)
+    }
+  end
+end
+```
+
+## API Reference
+
+### BehaviorAnalytics Module
+
+#### Class Methods
+
+- `BehaviorAnalytics.configure { |config| ... }` - Configure the gem
+- `BehaviorAnalytics.create_tracker(options = {})` - Create a tracker instance
+- `BehaviorAnalytics.track(event_name, properties: {}, **options)` - Simplified tracking
+- `BehaviorAnalytics.track_page_view(path:, properties: {}, **options)` - Track page view
+- `BehaviorAnalytics.track_click(element:, properties: {}, **options)` - Track click
+- `BehaviorAnalytics.track_conversion(conversion_name:, value: nil, properties: {}, **options)` - Track conversion
+- `BehaviorAnalytics.tracker` - Get default tracker instance
+
+### Tracker Class
+
+#### Methods
+
+- `track(context:, event_name:, event_type: :custom, metadata: {}, **options)` - Track event
+- `track_api_call(context:, method:, path:, status_code:, duration_ms: nil, **options)` - Track API call
+- `track_feature_usage(context:, feature:, metadata: {}, **options)` - Track feature usage
+- `flush` - Flush buffered events
+- `analytics` - Get analytics engine
+- `query` - Get query builder
+- `subscribe_to_stream(filter: nil, &block)` - Subscribe to event stream
+
+### Analytics Engine
+
+#### Methods
+
+- `event_count(context, options = {})` - Count events
+- `unique_users(context, options = {})` - Count unique users
+- `active_days(context, options = {})` - Count active days
+- `engagement_score(context, options = {})` - Calculate engagement score
+- `activity_timeline(context, period: :daily, options = {})` - Get activity timeline
+- `daily_activity(context, options = {})` - Get daily activity
+- `feature_usage_stats(context, options = {})` - Get feature usage statistics
+- `top_features(context, limit: 10, options = {})` - Get top features
+- `funnels` - Access funnel analysis
+- `cohorts` - Access cohort analysis
+- `retention` - Access retention analysis
+- `geographic` - Access geographic analytics
+- `referrer` - Access referrer analytics
+
+### Visit Manager
+
+#### Methods
+
+- `find_or_create_visit(visitor_token:, tenant_id: nil, user_id: nil, **options)` - Find or create visit
+- `find_active_visit(visitor_token, user_id = nil)` - Find active visit
+- `save_visit(visit)` - Save visit
+- `end_visit(visit_token)` - End visit
+- `link_user_to_visits(visitor_token, user_id)` - Link visits to user
+- `find_visits_by_user(user_id, limit: 100)` - Get user's visits
+- `find_visits_by_visitor(visitor_token, limit: 100)` - Get visitor's visits
+
+### User Resolver
+
+#### Methods
+
+- `identify_user(user_id, visitor_token: nil, request: nil)` - Identify user and merge visits
+- `merge_visits(visitor_token, user_id)` - Merge anonymous visits with user
+- `get_user_visits(user_id, limit: 100)` - Get user's visits
+- `get_visitor_visits(visitor_token, limit: 100)` - Get visitor's visits
+
+## Best Practices
+
+### 1. Visit Tracking
+
+- Enable visit tracking for web applications to get session analytics
+- Disable for API-only applications to reduce overhead
+- Use `visit_duration` to match your session timeout
+
+### 2. Device Detection
+
+- Use `:simple` for basic detection (no dependencies)
+- Use `:browser` or `:user_agent_parser` for more accurate detection (requires gems)
+- Consider caching device info to reduce processing
+
+### 3. Geolocation
+
+- Use geocoding service for production (Geocoder gem recommended)
+- Consider privacy implications of IP tracking
+- Cache geolocation results to reduce API calls
+
+### 4. Data Retention
+
+- Set appropriate retention periods based on your needs
+- Schedule cleanup jobs to run regularly
+- Archive old data before deletion if needed for compliance
+
+### 5. Performance
+
+- Use async processing for high-volume applications
+- Configure appropriate batch sizes
+- Monitor query performance and add indexes as needed
+- Consider using Redis or Elasticsearch adapters for scale
+
+### 6. Privacy & Compliance
+
+- Be transparent about data collection
+- Implement data deletion on user request
+- Consider anonymizing IP addresses
+- Comply with GDPR, CCPA, and other regulations
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nerdawey/behavior_analytics.
 
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run the test suite: `bundle exec rspec`
+6. Submit a pull request
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).