BT Visitor Insights Documentation

Overview

BT Visitor Insights is a free WordPress plugin that gives you a complete visitor analytics dashboard inside your wp-admin. It tracks page views, visitor locations, devices, browsers, operating systems, and referrers — all stored in your own database. No data is sent to third-party analytics services.

Unlike Google Analytics or similar tools, BT Visitor Insights runs entirely on your server. There are no external scripts injected into your pages, no cookies set on visitors, and no data shared with anyone. You get the insights you need while keeping full control of your data.

Installation

Download the plugin from the BT Visitor Insights page. In WordPress admin:

1. Go to Plugins › Add New › Upload Plugin
2. Select the bt-visitor-insights-1.0.0.zip file and click Install Now
3. Click Activate

That's it. The plugin creates its database tables on activation and begins tracking visitors immediately. You'll find the dashboard under the Visitor Insights menu in your admin sidebar.

Dashboard

The dashboard is your central hub for understanding your site traffic. It is divided into several sections:

Stats Cards

At the top of the dashboard, four stat cards give you a quick overview:

• Live Visitors — number of visitors active on your site in the last 5 minutes
• Page Views — total page views for the selected date range
• Unique Visitors — unique IP addresses for the selected date range
• Countries — number of distinct countries visitors came from

30-Day Bar Chart

A visual bar chart displays daily page views over the last 30 days. Each bar represents one day, making it easy to spot traffic trends, spikes, and quiet periods.

Data Tables

Below the chart, three tables show your top-performing data:

• Top Pages — most viewed pages with titles and view counts
• Top Referrers — where your traffic comes from (search engines, social media, direct links)
• Top Countries — geographic breakdown of your visitors

Visitor Detail

Click any IP address in the visitors table to open the visitor detail view. This shows the complete page-by-page browsing history for that visitor, including:

• Every page they visited with timestamps
• Their device type, browser, and operating system
• Their geographic location (city, region, country)
• The referrer URL that brought them to your site

Date Range Filter

Use the date range filter at the top of the dashboard to switch between time periods:

• Today — current day only
• 7 Days — last 7 days
• 30 Days — last 30 days (default)
• 90 Days — last 90 days
• All Time — all data in the database

Tracking

BT Visitor Insights tracks every front-end page view on your site. For each visit, the following data is recorded:

• Page URL and page title
• IP address (used for geolocation and visitor grouping)
• User agent (parsed into device type, browser, and OS)
• Referrer URL (the page that linked the visitor to your site)
• Timestamp

What Gets Skipped

The plugin automatically excludes the following from tracking:

• Bots and crawlers — Googlebot, Bingbot, and other known spiders are detected by user agent and excluded
• Logged-in administrators — admin users browsing the site are not tracked to avoid skewing data
• Do Not Track headers — visitors whose browsers send a DNT header are respected and not tracked
• Admin pages — requests to /wp-admin/ are not tracked
• AJAX and REST requests — only full page loads on the front end are recorded

Geolocation

BT Visitor Insights uses the ip-api.com free tier to look up visitor locations. When a new IP address is seen, the plugin sends a single request to ip-api.com to retrieve the city, region, and country. The result is cached in the database so the same IP is never looked up twice.

How It Works

1. A visitor loads a page on your site
2. The plugin checks if this IP has been geolocated before
3. If not, it queries ip-api.com/json/{ip} for the location
4. The city, region, and country are stored alongside the page view record
5. Future visits from the same IP reuse the cached location

Accuracy

IP geolocation is accurate to the city level for most visitors. Accuracy can vary for mobile networks and VPN users, where the reported location may reflect the network provider rather than the visitor's physical location. Country-level data is highly accurate for the vast majority of traffic.

Data Retention

BT Visitor Insights automatically purges old data to keep your database lean. A daily WordPress cron job runs to delete page view records older than 90 days.

The cron job is registered on plugin activation and removed on deactivation. If you deactivate and reactivate the plugin, the cron schedule is re-created automatically.

Privacy & GDPR

BT Visitor Insights is designed with privacy in mind:

• Self-hosted — all visitor data is stored in your WordPress database. No data is sent to external analytics platforms.
• No cookies — the plugin does not set any cookies on visitors' browsers.
• No frontend scripts — no JavaScript is added to your pages. Tracking is entirely server-side.
• Do Not Track — the plugin respects the DNT browser header. Visitors who opt out are not tracked.
• Auto-purge — data older than 90 days is automatically deleted, supporting data minimization principles.
• Admin exclusion — logged-in administrators are not tracked.

The only external request the plugin makes is to ip-api.com for geolocation lookups. This request includes the visitor's IP address. The ip-api.com service is queried server-side (not from the visitor's browser), and results are cached locally so each IP is only looked up once.

FAQ