﻿=== BT Visitor Insights ===
Contributors: tboulley
Tags: analytics, visitors, statistics, pageviews, geolocation
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight, self-hosted visitor analytics with IP geolocation, page views, device detection, and a real-time dashboard. No third-party scripts.

== Description ==

**BT Visitor Insights** is a privacy-friendly, self-hosted analytics plugin. Everything stays on your server — no Google Analytics, no third-party tracking scripts, no data sent to any external analytics platform.

Activate it and your dashboard starts filling with real visitor data: where they're from, what pages they viewed, what device they're on, and how long they've been around.

= Why use it? =

* **No third-party tracking.** All visitor data stays in your WordPress database.
* **Zero configuration.** Activate the plugin and data starts collecting immediately.
* **Lightweight.** No bulky frontend tracking script — tracking happens server-side, so it works alongside any caching plugin.
* **Real-time.** See who's on your site right now (last 15 minutes).
* **Respectful.** Honors the Do Not Track browser header and skips logged-in administrators.

= Features =

* Real-time active-visitor count
* IP geolocation — city, region, country, country flag
* Page view tracking with titles and referrers
* Device detection — desktop, mobile, tablet
* Browser and operating system breakdown
* Top pages, top referrers, top countries
* 30-day visual bar chart
* Per-visitor history — click any IP to see every page they viewed
* Date-range filters — today, 7 days, 30 days, 90 days, all time
* Auto-cleanup — old data is purged based on your configurable retention period (default 90 days)
* IP exclusion list and IP anonymization (in Settings)
* CSV export of visitors and page views
* Dashboard widget on the WP admin home screen
* Admin bar badge with live visitor count
* Skips bots, crawlers, and logged-in admins
* Respects the Do Not Track header

= Pro version =

A [Pro version](https://boulleytechnology.ca/bt-visitor-insights.php) adds:

* **Email digests** — daily or weekly HTML report with stats, top pages, and trend comparisons
* **Traffic-spike alerts** — get an email when page views exceed your normal baseline
* **Geo-blocking** — block or redirect visitors from specific countries
* **Scheduled CSV exports** — weekly or monthly automated email exports
* **Goals &amp; conversions** — track URL-based goals and unique converters
* **REST API access** — query stats, visitors, and page views via /wp-json/btvi/v1/
* **Multi-site rollup** — aggregate stats from multiple WordPress sites in one dashboard
* **White-label dashboard** — customize the menu label and page title for client sites
* **Unlimited data retention** — keep visitor history forever

The Pro version is sold separately and is not required to use this free plugin.

== Installation ==

1. From your WordPress admin, go to **Plugins &gt; Add New**.
2. Search for "BT Visitor Insights".
3. Click **Install Now**, then **Activate**.
4. A new **Visitor Insights** menu appears in your admin sidebar — click it to view your dashboard.
5. Data starts collecting on the next non-admin page view.

Or install manually:

1. Download the plugin ZIP.
2. Go to **Plugins &gt; Add New &gt; Upload Plugin** and upload the ZIP.
3. Activate the plugin.

== Frequently Asked Questions ==

= Does this use Google Analytics or any third-party tracking scripts? =

No. BT Visitor Insights is fully self-hosted. No tracking scripts are added to your frontend and no analytics data is sent to any third-party platform.

= What data is collected? =

Visitor IP address, page URL, page title, referrer, browser, operating system, and device type. All data is stored in your own WordPress database.

= Does it work with caching plugins? =

Yes. Tracking is handled server-side rather than via a frontend JavaScript snippet, so it works alongside most caching plugins (WP Rocket, W3 Total Cache, LiteSpeed Cache, etc.).

= Does it comply with GDPR? =

The plugin respects the Do Not Track browser header and skips logged-in administrators. Visitor IPs can be optionally anonymized via the Settings page. You are still responsible for disclosing any visitor tracking in your site's privacy policy.

= How do I exclude my own visits? =

Go to **Visitor Insights &gt; Settings** and add your IP address to the exclusion list. Logged-in administrators are also skipped automatically.

= How long is data retained? =

90 days by default. You can change the retention period in Settings (0 = unlimited, or 1–3650 days). Old data is purged automatically by a daily cron job.

= Can I delete all collected data? =

Yes. Go to **Visitor Insights &gt; Settings** and use the "Clear All Data" button under Danger Zone.

== External Services ==

This plugin uses the **ip-api.com** geolocation API to look up the city, region, and country for each new visitor IP address. This request is made server-side from your WordPress installation when a visitor is first seen.

* Service: ip-api.com
* What is sent: the visitor's IP address
* When: once per unique visitor IP, server-side
* Privacy policy: https://ip-api.com/docs/legal
* Terms of service: https://ip-api.com/docs/legal

No data is sent to Boulley Technology or any other third party.

== Screenshots ==

1. Real-time dashboard with visitor count, top pages, top referrers, top countries, and 30-day chart.
2. Per-visitor history — click any IP to see every page that visitor viewed.
3. Settings page — data retention, IP exclusion, IP anonymization, CSV export.
4. Dashboard widget on the WordPress admin home screen.

== Changelog ==

= 1.0.1 =
* Switched geolocation API from ipwho.is to ip-api.com for reliable legal documentation compliance.

= 1.0.0 =
* Initial release on WordPress.org.
* Real-time visitor count.
* IP geolocation via ipwho.is (city, region, country) over HTTPS.
* Page view tracking with titles and referrers.
* Device, browser, and OS detection.
* Top pages, referrers, and countries.
* 30-day bar chart.
* Per-visitor page history.
* Date-range filters.
* Configurable data retention with daily auto-cleanup.
* IP exclusion list and IP anonymization.
* CSV export.
* Dashboard widget and admin bar badge.
* Respects Do Not Track and skips logged-in admins.

== Upgrade Notice ==

= 1.0.0 =
First public release.
