=== Opti-Behavior ===
Contributors: optiuser
Tags: analytics, heatmap, user tracking, session recording, behavior analytics
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Transform your WordPress site with powerful analytics! Track user behavior with beautiful heatmaps, session recordings, and real-time insights.

== Description ==

Opti-Behavior is a comprehensive user behavior analytics plugin for WordPress that helps you understand how visitors interact with your website. Make data-driven decisions to improve user experience and boost conversions.

= Key Features =

* **Visual Heatmaps** - See where users click, move, and scroll on your pages with separate mobile and desktop views
* **Session Recordings** - Watch real user sessions to understand behavior patterns
* **Real-time Analytics** - Monitor visitor activity as it happens
* **Page Performance Tracking** - Identify high-performing and underperforming pages
* **User Journey Analysis** - Track visitor paths through your site
* **Bot Detection & Tracking** - Automatic server-side bot detection to filter out non-human traffic
* **File Storage System** - Optional file-based storage for high-traffic sites to prevent database bloat
* **Performance Optimizer** - Automatic database indexing and optimization for large datasets
* **Mobile/Desktop Separation** - Separate heatmap tracking and visualization for mobile and desktop devices
* **Privacy-Focused** - GDPR compliant with built-in data protection features
* **Lightweight & Fast** - Optimized code that won't slow down your site
* **Easy to Use** - Intuitive dashboard with beautiful visualizations

= Perfect For =

* E-commerce sites looking to optimize conversion funnels
* Content creators wanting to understand reader engagement
* Web designers testing new layouts and designs
* Marketing teams analyzing campaign effectiveness
* Anyone who wants to improve their website's user experience

= Privacy & Data Protection =

Opti-Behavior takes privacy seriously:

* GDPR compliant data collection
* Configurable data retention periods
* Option to anonymize IP addresses
* Respect for Do Not Track headers
* User consent management
* Secure data storage
* Complete data deletion on uninstall (optional)
* All data stored locally in your WordPress database
* No external tracking or data sharing with third parties

= Technical Features =

* Clean, well-documented code
* WordPress coding standards compliant
* Secure database queries with prepared statements
* Proper data sanitization and escaping
* Efficient database schema with automatic indexing
* Automated data cleanup and retention management
* Flexible storage options (database or file-based)
* Batch processing for high-traffic optimization
* Debug mode with comprehensive logging
* Bot filtering to exclude non-human traffic
* Multisite compatible
* Performance optimizations for large datasets

== Installation ==

= Automatic Installation =

1. Log in to your WordPress admin panel
2. Navigate to Plugins > Add New
3. Search for "Opti-Behavior"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin zip file
2. Log in to your WordPress admin panel
3. Navigate to Plugins > Add New > Upload Plugin
4. Choose the downloaded zip file and click "Install Now"
5. After installation, click "Activate Plugin"

= After Activation =

1. Navigate to Opti-Behavior in your WordPress admin menu
2. Configure your tracking preferences in Settings
3. Start collecting data immediately
4. View analytics in the Dashboard

== Frequently Asked Questions ==

= Does this plugin slow down my website? =

No! Opti-Behavior is designed to be lightweight and efficient. The tracking script is minified and loads asynchronously, ensuring minimal impact on page load times.

= Is this plugin GDPR compliant? =

Yes! Opti-Behavior includes features for GDPR compliance including IP anonymization, data retention controls, and user consent management. All data is stored locally in your WordPress database and is never sent to external servers. However, you are responsible for configuring these settings appropriately for your use case and ensuring your privacy policy discloses the data collection.

= Can I export my data? =

Yes! The plugin includes export functionality for all collected data in CSV format.

= Does this work with caching plugins? =

Yes! Opti-Behavior is compatible with popular caching plugins like WP Super Cache, W3 Total Cache, and WP Rocket.

= Will this work on multisite? =

Yes! Opti-Behavior is multisite compatible and can be activated network-wide or on individual sites.

= Does this plugin call any external services? =

Yes, this plugin makes limited use of external services for geolocation functionality. See the "External Services" section below for full details. All JavaScript libraries (Chart.js, Leaflet, heatmap.js) are bundled locally within the plugin. All analytics data is stored locally in your WordPress database.

= What data does this plugin collect? =

The plugin collects:
* Page views and URLs
* Click positions and elements
* Mouse movements and scroll depth
* Session duration and timestamps
* Referrer information
* Device and browser information (user agent)
* Anonymized IP addresses (optional)
* Approximate location based on browser timezone (no external API calls)

No personally identifiable information (PII) is collected by default. All data is stored locally in your WordPress database.

= Can I delete all data when uninstalling? =

Yes! In the plugin settings, you can enable "Delete all data on uninstall". When enabled, all database tables and options will be removed when you uninstall the plugin.

= How do I get support? =

For support, please use the WordPress.org support forums for this plugin. We monitor the forums regularly and will respond as quickly as possible.

= What is the File Storage System? =

For high-traffic websites, storing all analytics data in the database can cause performance issues. The File Storage System allows you to store event data in organized JSON files instead, reducing database load. You can enable this in Settings > Storage Options. File storage uses batch processing and compression to optimize performance.

= Does the plugin detect and filter bot traffic? =

Yes! Opti-Behavior includes automatic server-side bot detection that identifies and filters out traffic from search engine crawlers, monitoring bots, and other non-human visitors. This ensures your analytics data reflects real user behavior. The bot tracker recognizes all major search engines (Google, Bing, Yahoo, etc.) and common bots.

= Can I see mobile and desktop heatmaps separately? =

Yes! The plugin automatically tracks and displays separate heatmaps for mobile and desktop devices. This allows you to understand how user behavior differs between device types and optimize your site accordingly for each platform.

== External Services ==

This plugin connects to external services in specific circumstances:

= IP Geolocation API (ip-api.com) =

**What it is:** A free IP geolocation service that provides geographic information based on IP addresses.

**When it's used:** When a visitor accesses your site and their location cannot be determined from CloudFlare headers (if CloudFlare is not in use), the plugin may make a server-side API call to ip-api.com to determine the visitor's approximate geographic location (country, region, city, timezone) based on their IP address.

**What data is sent:** Only the visitor's IP address is sent to ip-api.com. No other personally identifiable information is transmitted.

**Why it's needed:** This geolocation data is used to provide geographic analytics in the dashboard (e.g., visitor location maps, country/region statistics).

**Caching:** Results are cached for 1 hour to minimize API requests.

**Rate limits:** The free tier has a rate limit of 45 requests per minute.

**Privacy & Terms:**
* Service homepage: https://ip-api.com/
* Terms of service: https://ip-api.com/docs/legal
* Privacy policy: https://ip-api.com/docs/legal (see Privacy section)
* Data handling: ip-api.com may log IP addresses for their own analytics. Please review their privacy policy for details.

**Note:** If CloudFlare is detected, the plugin uses CloudFlare's provided geolocation headers instead and does NOT make external API calls.

= OpenStreetMap Tiles =

**What it is:** Map tiles for displaying the real-time visitor map visualization.

**When it's used:** When you view the real-time visitor map in the admin dashboard.

**What data is sent:** Map tile requests are made directly by your browser (not by the plugin server) to OpenStreetMap tile servers. Standard HTTP request data (IP address, user agent) is sent as part of normal browser requests.

**Why it's needed:** To display the interactive map showing visitor locations.

**Privacy & Terms:**
* Service homepage: https://www.openstreetmap.org/
* Tile usage policy: https://operations.osmfoundation.org/policies/tiles/
* Privacy policy: https://wiki.osmfoundation.org/wiki/Privacy_Policy

== Screenshots ==

1. Dashboard overview with real-time analytics and key metrics
2. Visual heatmap showing click patterns on a page
3. Session recordings list with filtering options
4. Detailed analytics for individual pages
5. Settings panel with privacy and data retention options
6. User journey visualization showing visitor paths

== Changelog ==

= 1.0.4 =
* Enhancement: Added file-based storage system for high-traffic sites
* Enhancement: Implemented automatic bot detection and filtering
* Enhancement: Added performance optimizer with automatic database indexing
* Enhancement: Separate mobile and desktop heatmap tracking and visualization
* Enhancement: Batch processing for improved performance
* Enhancement: Enhanced debug logging system
* Enhancement: Added Lucide icon library (v0.554.0, ISC License) for modern UI
* Security: Replaced error_log() with WordPress-compliant debug manager
* Security: Replaced direct filesystem operations with WP_Filesystem API
* Security: Replaced unlink() with wp_delete_file() for file deletion
* Code Quality: WordPress coding standards compliance improvements
* Code Quality: Improved data sanitization and validation
* Compatibility: Tested up to WordPress 6.8

= 1.0.3 =
* Security: Fix Unsafe SQL calls
* Security: Fix files and directories locations use
* Security: Moved inline CSS to external stylesheet
* Security: Moved inline JS to external stylesheet
* Follows WordPress coding standards
* Plugin Check validation passed

= 1.0.2 =
Review and fix all the issues listed in the review email.

= 1.0.1 =
* Security: Enhanced sanitization for $_SERVER variables
* Security: Improved json_decode() data sanitization
* Security: Moved inline CSS to external stylesheet for WordPress compliance
* Code Quality: Added proper sanitization for all user inputs
* Code Quality: Enhanced data validation in AJAX handlers
* Compatibility: Verified all security checks are in place

= 1.0.0 =
* Initial release
* Visual heatmap tracking
* Session recording functionality
* Real-time analytics dashboard
* Page performance metrics
* User journey tracking
* GDPR compliance features
* Data export functionality
* Multisite support
* Debug mode for troubleshooting

== Upgrade Notice ==

= 1.0.4 =
Major update with file storage system, bot detection, performance optimizations, and WordPress coding standards compliance. Recommended for all users, especially high-traffic sites.

= 1.0.3 =
Important security update with enhanced SQL security and WordPress coding standards compliance. Recommended for all users.

= 1.0.1 =
Important security update with enhanced input sanitization and WordPress coding standards compliance. Recommended for all users.

= 1.0.0 =
Initial release of Opti-Behavior. Install to start tracking user behavior on your WordPress site.

== Privacy Policy ==

Opti-Behavior collects user interaction data to provide analytics insights. This data includes:

* Page URLs and titles
* Click coordinates and target elements
* Mouse movement patterns
* Scroll depth
* Session timestamps
* Referrer URLs
* Browser and device information
* IP addresses (can be anonymized)
* Approximate location based on browser timezone (client-side only, no external services)

**Data Storage:** All analytics data is stored locally in your WordPress database.

**External Services:** This plugin may make API calls to ip-api.com for IP geolocation when CloudFlare headers are not available. Only the visitor's IP address is sent to this service. See the "External Services" section above for complete details on what data is shared and under what circumstances.

**User Rights:** You have full control over data retention and deletion. Users can request data deletion at any time.

When using this plugin, ensure your site's privacy policy discloses:
* What data is being collected
* How long it is retained
* Who has access to it
* How users can request deletion
* That data is stored locally and not shared with third parties

== Third-Party Libraries ==

This plugin bundles the following open-source libraries:

= Chart.js =
* Version: 4.4.0
* License: MIT License
* Homepage: https://www.chartjs.org/
* Used for: Rendering analytics charts and graphs

= Leaflet =
* Version: 1.9.4
* License: BSD 2-Clause License
* Homepage: https://leafletjs.com/
* Used for: Real-time visitor map visualization

= heatmap.js =
* Version: 2.0.5
* License: MIT License
* Homepage: https://www.patrick-wied.at/static/heatmapjs/
* Used for: Generating visual heatmaps of user interactions

= Lucide =
* Version: 0.554.0
* License: ISC License
* Homepage: https://lucide.dev/
* Used for: Icon library for the admin interface

All bundled libraries use GPL-compatible licenses (MIT, BSD 2-Clause, and ISC) and are included locally within the plugin. See THIRD-PARTY-LICENSES.md in the plugin directory for full license texts.

== Credits ==

Developed by OptiUser