Skip to content

TRACKING_README.md

Latest commit

 

History

History
executable file
·
264 lines (219 loc) · 7.57 KB

TRACKING_README.md

File metadata and controls

executable file
·
264 lines (219 loc) · 7.57 KB

Big Brain Coding - Visitor Tracking System

Overview

This comprehensive tracking system captures detailed visitor analytics for marketing and business intelligence purposes. The system logs data locally to your server with organized directory structure and provides rich analytics.

What Gets Tracked

✅ Automatically Tracked

  • Page Views - Every page visit with timestamp
  • Session Data - Session duration, start/end times
  • Device Information - Browser, OS, device type (mobile/desktop/tablet)
  • Screen/Viewport - Screen dimensions and viewport size
  • User Interactions - Clicks, scroll depth, form submissions
  • Navigation - Referrer URLs, exit pages
  • IP Address - Client IP (from NGINX headers)
  • Geographic Data - Timezone, language preferences
  • Performance - Time spent on each page

📊 Analytics Provided

  • Visitor Sessions - Unique session tracking
  • Page Popularity - Most/least visited pages
  • Device Distribution - Mobile vs desktop usage
  • Browser Statistics - Browser market share
  • Engagement Metrics - Time on site, scroll depth
  • Conversion Tracking - Form submissions, contact interactions

File Structure

~/bigbraincoding.com/
├── 2024/
│   ├── 12/
│   │   ├── 25/
│   │   │   ├── 14-30-45-abc12345.json    # Individual event
│   │   │   ├── 14-31-22-def67890.json    # Individual event
│   │   │   └── 2024-12-25-summary.json   # Daily summary
│   │   └── 26/
│   │       └── ...
│   └── 2025/
│       └── 01/
│           └── ...

Data Format

Individual Event File

{
  "timestamp": "2024-12-25T14:30:45.123Z",
  "sessionId": "1703521845123-abc12345",
  "eventType": "pageview",
  "pageUrl": "https://bigbraincoding.com/services",
  "referrer": "https://google.com",
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "deviceInfo": {
    "browser": "Chrome",
    "browserVersion": "120",
    "os": "Windows",
    "osVersion": "10",
    "deviceType": "desktop",
    "screenWidth": 1920,
    "screenHeight": 1080,
    "viewportWidth": 1920,
    "viewportHeight": 937,
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "eventData": {
    "scrollDepth": 75,
    "element": "button",
    "elementId": "contact-btn"
  },
  "timeOnPage": 45000
}

Daily Summary File

{
  "events": [
    {
      "timestamp": "2024-12-25T14:30:45.123Z",
      "eventType": "pageview",
      "sessionId": "1703521845123-abc12345",
      "pageUrl": "/services",
      "deviceType": "desktop",
      "browser": "Chrome"
    }
  ],
  "totalEvents": 150,
  "uniqueSessions": ["1703521845123-abc12345", "1703521900000-def67890"],
  "lastUpdated": "2024-12-25T23:59:59.999Z"
}

Usage

1. Automatic Tracking

The tracking system is automatically initialized on all pages. No additional setup required.

2. Custom Event Tracking

import { trackEvent } from '@/lib/tracking';

// Track custom business events
trackEvent('contact_form_submitted', {
  formType: 'general_inquiry',
  source: 'services_page'
});

trackEvent('project_viewed', {
  projectId: 'mealforge',
  source: 'homepage'
});

3. Analyzing Data

Run the analysis script to get insights:

node scripts/analyze-tracking.js

Example output:

🔍 Big Brain Coding - Tracking Data Analysis
=============================================

📊 Found data for years: 2024

📅 2024 Analysis:
──────────────────────────────────────────────────
📈 Total Events: 1,250
👥 Unique Sessions: 89
📄 Page Views: 450
🖱️  Clicks: 800
📝 Form Submissions: 12
⏱️  Average Session Duration: 145s

📱 Device Distribution:
   desktop: 320 (71.1%)
   mobile: 120 (26.7%)
   tablet: 10 (2.2%)

🌐 Browser Distribution:
   Chrome: 280 (62.2%)
   Safari: 90 (20.0%)
   Firefox: 50 (11.1%)
   Edge: 30 (6.7%)

📄 Top Pages:
   /: 150 views (33.3%)
   /services: 120 views (26.7%)
   /projects: 80 views (17.8%)
   /contact: 60 views (13.3%)
   /about: 40 views (8.9%)

Privacy & Compliance

GDPR Compliance

  • Data is stored locally on your server
  • No third-party tracking services
  • User consent can be integrated with your existing consent management
  • Data can be easily deleted or exported

Data Retention

  • Logs are organized by date for easy cleanup
  • Old data can be automatically archived or deleted
  • Summary files provide aggregated data for long-term analysis

Configuration

Environment Variables

# Optional: Custom log directory
TRACKING_LOG_DIR=/custom/path/to/logs

NGINX Integration

The system works with your existing NGINX setup and captures:

  • Client IP addresses
  • User-Agent strings
  • Referrer information
  • Request timestamps

Business Intelligence

Marketing Insights

  • Traffic Sources - See which pages drive the most engagement
  • Conversion Funnels - Track user journey from homepage to contact
  • Content Performance - Identify most engaging content
  • Device Optimization - Understand mobile vs desktop usage

Customer Engagement

  • Session Duration - Measure engagement quality
  • Page Depth - Understand content consumption
  • Interaction Patterns - See how users interact with your site
  • Exit Points - Identify where users leave

Technical Analytics

  • Browser Compatibility - Ensure site works across browsers
  • Device Performance - Optimize for most common devices
  • Page Load Performance - Track user experience metrics
  • Error Tracking - Monitor for technical issues

Troubleshooting

No Data Being Collected

  1. Check browser console for errors
  2. Verify /api/tracking endpoint is accessible
  3. Ensure file permissions allow writing to log directory
  4. Check network tab for failed requests

Missing IP Addresses

  1. Ensure NGINX is forwarding X-Forwarded-For headers
  2. Check proxy configuration
  3. Verify server can access client IP

Performance Issues

  1. Monitor log file sizes
  2. Implement log rotation if needed
  3. Consider archiving old data
  4. Optimize summary file generation

Security Considerations

Data Protection

  • Logs contain sensitive information (IPs, user agents)
  • Store logs securely with appropriate permissions
  • Consider encryption for sensitive data
  • Implement access controls for log files

Rate Limiting

  • Consider implementing rate limiting on /api/tracking
  • Monitor for abuse or excessive requests
  • Implement request throttling if needed

Future Enhancements

Planned Features

  • Real-time Dashboard - Live analytics interface
  • Export Functionality - CSV/JSON data export
  • Advanced Filtering - Date ranges, device types, etc.
  • Email Reports - Automated daily/weekly summaries
  • A/B Testing - Track different page versions
  • Goal Tracking - Custom conversion goals

Integration Opportunities

  • Google Analytics - Complement with GA4
  • CRM Systems - Link visitor data to leads
  • Email Marketing - Track email campaign performance
  • Social Media - Monitor social traffic sources

Support

For questions or issues with the tracking system:

  1. Check the browser console for JavaScript errors
  2. Review server logs for API endpoint issues
  3. Verify file permissions and directory structure
  4. Test with the analysis script to validate data collection

The tracking system provides comprehensive visitor analytics while maintaining privacy and compliance standards. Use this data to optimize your website, improve user experience, and drive business growth.