# Smart Click Tracker

A lightweight WordPress plugin to track clicks on specific elements of your website and display comprehensive statistics with beautiful charts.

**Version:** 1.1.0
**Requires WordPress:** 5.0+
**Requires PHP:** 7.4+
**License:** GPL v2 or later

## Features

- **Element Click Tracking** – Track clicks on any element using CSS selectors
- **Advanced Analytics** – Visual charts for clicks over time, hourly distribution, and device breakdown
- **Date Range Filtering** – Filter analytics data by custom date ranges and specific trackers
- **Device Detection** – See how users interact across desktop, mobile, and tablet devices
- **User Tracking Controls** – Choose to track logged-in users, anonymous users, or both
- **Data Retention** – Automatic cleanup of old tracking data based on your retention settings
- **IP Anonymization** – Built-in option to anonymize visitor IP addresses
- **Rate Limiting** – Prevents duplicate click tracking from rapid successive clicks
- **Lightweight** – Minimal impact on page load times with asynchronous tracking

## Installation

1. Upload the `smart-click-tracker` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to 'Click Tracker' in the admin menu to start creating trackers

## Usage

### Creating a Tracker

1. Go to **Click Tracker > Add New** in the WordPress admin
2. Enter a name for your tracker (e.g., "Contact Button")
3. Enter the CSS selector for the element you want to track (e.g., `.contact-button` or `#contact-form-submit`)
4. Add an optional description
5. Click **Create Tracker**

### Viewing Statistics

1. Go to **Click Tracker > Dashboard** to see all trackers with click counts
2. Click **View Stats** next to any tracker for a detailed modal with charts
3. Go to **Click Tracker > Analytics** for advanced analytics with date range filters

### Configuring Settings

1. Go to **Click Tracker > Settings**
2. Configure tracking for logged-in users, anonymous users, data retention, and IP anonymization
3. Click **Save Settings**

## CSS Selector Examples

| Selector | What it tracks |
|---|---|
| `.classname` | Elements with class "classname" |
| `#id` | Element with ID "id" |
| `a[href*="example.com"]` | Links containing "example.com" in the href |
| `.parent .child` | Nested elements |
| `.btn, .cta` | Multiple elements with one tracker |

## FAQ

**Q: Will this slow down my website?**
A: No. The tracking script only loads when active trackers exist, and click events are sent asynchronously.

**Q: Can I track multiple elements with one tracker?**
A: Yes. Use comma-separated CSS selectors like `.button, .cta` to track multiple elements.

**Q: Is this plugin GDPR compliant?**
A: The plugin includes IP anonymization and data retention controls. No cookies are set and no data is sent to third parties. Include tracking details in your privacy policy for full compliance.

**Q: Does this work with page builders?**
A: Yes. It works with Elementor, Beaver Builder, Divi, and all other page builders.

## Changelog

### 1.1.0
- Security: Added capability check to uninstall routine
- Security: Separated admin and public nonce actions to prevent cross-context reuse
- Security: Fixed XSS vulnerability in admin JavaScript AJAX response rendering
- Security: Fixed settings sanitization dropping values for unchecked checkboxes
- Performance: Replaced N+1 per-tracker queries with bulk query on dashboard
- Performance: Added database indexes on events table for faster analytics
- Performance: Automatic database upgrade routine for existing installations
- Fix: IP validation now works on local/staging environments with private IPs
- Removed console.log statements from production JavaScript

### 1.0.9
- Fixed analytics page not rendering charts and filter controls
- Fixed edit tracker page not loading existing tracker data
- Removed duplicate hook registration in admin class
- Code quality improvements

### 1.0.8
- WordPress Plugin Directory compliance (smarcltr prefix)
- Fixed JavaScript click tracking and statistics modal
- Chart.js integration for analytics
- Enhanced security with rate limiting and input validation
- Performance optimizations with multi-layer caching

### 1.0.7
- Improved analytics interface
- Fixed filter form layout

### 1.0.5
- Initial release

## Support

For support requests, feature suggestions, or bug reports, please visit the [WordPress support forum](https://wordpress.org/support/plugin/smart-click-tracker/).

## License

This plugin is licensed under the GPL v2 or later.

Copyright © 2026 Coresol Studio