# ADCT Contact Click Tracker

A WordPress plugin for contact-click tracking, marketing attribution, and session-based admin reporting. Free and fully functional — no license key required.

**Created by [Benjamin Clar](https://github.com/benjamindimalanta)**

---

## Features

- **Contact click tracking** — WhatsApp, phone, showroom, floating buttons, Elfsight widgets, footer `tel:` links
- **Marketing attribution** — 30-day first-touch cookie for UTMs, `gclid`, landing URL, referrer, entry source
- **Session grouping** — One collapsible admin card per browser tab session; all clicks preserved inside
- **Visitor context** — Device, browser, country/region (geo lookup; see Third-party services in readme.txt)
- **WooCommerce ready** — Product snapshot (title, price, mileage, image) on product pages
- **Site-wide tracking** — Landing pages, brand archives, and product pages
- **Admin dashboard** — Filters, pagination, CSV export
- **WP Rocket compatible** — Script exclusions for cache/minify/defer

---

## Requirements

- WordPress 5.8+
- PHP 7.4+
- WooCommerce (optional, for product-page enrichment)

---

## Installation

1. Download or clone this repository into `wp-content/plugins/adct-contact-click-tracker/`
2. Activate **ADCT Contact Click Tracker** in **Plugins**
3. The database table is created automatically on activation
4. Clear any page cache (WP Rocket, Cloudflare, etc.) after install or updates

### Theme integration (product pages)

Add `data-track="contact"` attributes to contact links you want tracked, for example:

```html
<a href="https://wa.me/971..." 
   data-track="contact"
   data-contact-type="whatsapp"
   data-agent-id="1"
   data-agent-name="Sales Agent"
   data-source="product_card">
   WhatsApp
</a>
```

Supported `data-contact-type` values: `whatsapp`, `phone`, `showroom_landline`, `floating_whatsapp`, `floating_phone`.

Elfsight and footer phone links are detected automatically on all front-end pages.

---

## Google Ads URL template

Append UTMs using Google dynamic parameters:

```
utm_source=google&utm_medium=cpc&utm_campaign={campaignname}&utm_id={campaignid}&utm_term={keyword}&utm_content={creative}
```

---

## Admin

After activation, open **ADCT Contact Click Tracker** in the WordPress admin sidebar.

- Sessions are grouped by browser tab (`session_id` in sessionStorage)
- Expand a session to see marketing data and every click in chronological order
- **Export CSV** downloads all individual click rows (not grouped)

---

## File structure

```
adct-contact-click-tracker/
├── adct-contact-click-tracker.php      # Main plugin bootstrap
├── readme.txt                 # WordPress.org listing
├── assets/
│   ├── entry-capture.js       # Attribution cookie + session ID (all pages)
│   └── tracker.js             # Click capture (all pages)
└── includes/
    ├── class-adct-admin.php   # Admin UI
    ├── class-adct-ajax.php    # AJAX handlers
    ├── class-adct-database.php# Database layer
    └── class-adct-visitor.php # Device / geo helpers
```

---

## Changelog

See [readme.txt](readme.txt) for the WordPress.org changelog.

---

## License

GPL-2.0-or-later. See [LICENSE](LICENSE).

---

## Author

**Benjamin Clar**  
GitHub: [@benjamindimalanta](https://github.com/benjamindimalanta)