BT Visitor Insights Documentation

Self-hosted visitor analytics for WordPress. Track page views, devices, locations, and referrers — all without third-party services.

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.

Minimal configuration. Activate the plugin and tracking starts immediately. The dashboard appears under the Visitor Insights menu in wp-admin. A Settings page lets you adjust data retention, exclude IPs, and enable IP anonymization.

Installation

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

Go to Plugins › Add New › Upload Plugin
Select the bt-visitor-insights-2.0.0.zip file and click Install Now
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.

No API keys needed. BT Visitor Insights works out of the box. Geolocation uses a free service that requires no registration or API key.

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 15 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

Logged-in admins are excluded. If you are logged in as an administrator and browse your site, your visits will not appear in the dashboard. This is by design to keep your analytics accurate.

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

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

Free tier limits. The ip-api.com free tier allows 45 requests per minute. For most WordPress sites, this is more than sufficient. If you exceed the limit, lookups are simply skipped until the next minute — no errors or tracking interruptions.

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 deletes records older than your configured limit (default 90 days).

Free — configurable up to 90 days
Pro — configurable up to 3650 days, or set to 0 for unlimited retention

Automatic cleanup. The retention cron runs daily via wp_cron. If retention is set to 0 (Pro), the cron skips deletion and all data is kept indefinitely.

Settings

Go to Visitor Insights › Settings to configure the plugin:

Data Retention — set how many days of visitor and page view data to keep (1–3650 days, default 90). Old records are automatically deleted daily.
Exclude IP Addresses — enter one IP per line to prevent those visitors from being tracked (useful for your own IP or team IPs).
IP Anonymization — when enabled, only the first three octets of each IP are stored (e.g. 192.168.1.xxx). Geolocation still works at city level. Helps with GDPR compliance.

CSV Export

Export your data at any time from Visitor Insights › Settings under the Export Data section. Two CSV formats are available:

Visitors CSV — one row per visitor with IP, location, browser, OS, device, first visit, last visit, and total visits.
Page Views CSV — one row per page view with IP, URL, title, referrer, and timestamp.

Send Message to Visitor PRO

Available in BT Visitor Insights Pro. Send a real-time message to any live visitor directly from the dashboard. The message appears as a popup on their screen within 15 seconds.

How to Send a Message

Go to Visitor Insights in wp-admin
Find the visitor in the Recent Visitors table
Click the 💬 Message button in their row
Type your message in the modal and click Send Message

How delivery works. The visitor's browser polls for pending messages every 15 seconds. The popup appears on their current page within that window, or immediately on their next page load. Messages auto-dismiss after 30 seconds.

Requires an active session. The visitor must have a session cookie set (established on their first page view). Visitors who arrived before 1.3.0 was activated may not receive messages until they load a new page.

UTM Campaign Tracking PRO

Automatically captures UTM parameters from incoming URLs and attributes them to page views using last-touch attribution. Parameters tracked: utm_source, utm_medium, utm_campaign, utm_term, utm_content.

UTM values are stored in a 30-day cookie so they persist across multiple page views in the same session. A dedicated Campaigns table in the dashboard shows top sources, mediums, and campaigns by visits and unique visitors.

Example. Add ?utm_source=newsletter&utm_medium=email&utm_campaign=launch to any link pointing to your site. All page views from that session will be attributed to that campaign.

Email Digests PRO

Receive a beautifully formatted HTML email summarising your visitor stats on a daily or weekly schedule. Each digest includes:

Total page views and unique visitors for the period
Period-over-period comparison with ▲▼ percentage change
Top 5 pages, referrers, and countries

Configure digests under Visitor Insights › Settings › Email Digests. You can also send a test email from the Settings page to preview the layout.

Traffic Spike Alerts PRO

Get an instant email alert when your site experiences unusual traffic. Every 15 minutes, the plugin counts page views in that window and compares it to a 7-day rolling baseline for the same hour of day.

Threshold — alert fires when traffic exceeds X× your baseline (default 2×)
Cooldown — one alert per hour maximum to prevent inbox flooding during a sustained spike
Minimum — at least 5 page views required before alerting

Configure under Settings › Traffic Spike Alerts. Use the test button to preview the alert email.

Goal & Conversion Tracking PRO

Define URL-based goals and track how many visitors reach them. Useful for measuring sign-up confirmations, checkout completions, thank-you pages, or any other key destination.

Match Types

Contains — URL includes the pattern anywhere (default)
Exact — URL matches exactly
Starts with — URL begins with the pattern
Ends with — URL ends with the pattern
Regex — full regular expression match

Goals are managed directly from the main dashboard. One completion per visitor per goal per day is recorded. The dashboard table shows total completions and unique converters for each goal.

Geo-Blocking PRO

Block or redirect visitors from specific countries. The check runs before any database writes, so blocked visitors leave no trace in your analytics.

Actions

Skip tracking — visitor sees the site normally but is not recorded (default)
Block access — visitor sees a 403 error with a configurable message
Redirect — visitor is redirected to a URL of your choice

Configure under Settings › Geo-Blocking. Enter one ISO 3166-1 alpha-2 country code per line (e.g. US, GB, CN).

Scheduled CSV Exports PRO

Automatically email a CSV export of your visitor data on a regular schedule. Each email includes two attachments:

Visitors CSV — all visitor records with location, device, browser, and visit counts
Page Views CSV — all page view records including UTM data (up to 50,000 rows)

Available schedules: weekly (every Monday at 6am) and monthly (first of each month at 6am). Exports are sent to the address configured in Email Digests. Configure under Settings › Scheduled CSV Exports.

REST API PRO

Access your visitor data programmatically via the WordPress REST API. Authenticate by passing your API key in the X-BTVI-Key request header (or as a ?btvi_key= query parameter).

Endpoints

GET /wp-json/btvi/v1/stats?range=7 — summary stats (views, visitors, live count, top pages, top countries)
GET /wp-json/btvi/v1/visitors?page=1&per_page=50 — paginated visitor list
GET /wp-json/btvi/v1/pageviews?range=7&page=1 — paginated page view list

Valid range values: today, 7, 30, 90, all. Paginated responses include X-WP-Total and X-WP-TotalPages headers. Generate and revoke your API key under Settings › REST API.

White-Label Dashboard PRO

Customize the dashboard for client sites by replacing the menu label and page heading with your own branding. Enable white-label mode under Settings › White-Label Dashboard and set:

Menu Label — replaces "Visitor Insights" in the admin sidebar
Page Title — replaces the dashboard and settings page headings

Multi-Site Rollup PRO

Aggregate visitor stats from multiple WordPress sites into a single dashboard. This site acts as the primary hub; each satellite site must have BT Visitor Insights Pro installed with a generated API key.

Setup

On each satellite site, go to Settings › REST API and generate an API key
On your primary site, go to the main dashboard and click + Add Site in the Multi-Site Rollup section
Enter the satellite site URL and API key
Stats are fetched automatically and cached for 5 minutes

Each site card shows total views, unique visitors, and live visitor count for the selected date range. Click Open Dashboard → to go directly to that site's wp-admin.

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.
Minimal frontend scripts — a small polling script is added only to support the Send Message feature. Core 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.

IP addresses are personal data. Under GDPR, IP addresses are considered personal data. Because BT Visitor Insights stores IP addresses, you should mention this in your site's privacy policy. The plugin helps with compliance through auto-purge and DNT support, but you are responsible for your site's overall GDPR compliance.

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.

Changelog

v2.0.0

REST API (Pro) — /btvi/v1/stats, /visitors, /pageviews with API key auth; generate and revoke keys from Settings
Multi-site rollup (Pro) — aggregate stats from satellite sites in one dashboard with 5-minute cache

v1.9.0

Goal & conversion tracking (Pro) — URL-based goals with contains/exact/regex match types, completions and unique converter counts
Goal management UI directly in the main dashboard — add, edit, delete goals without leaving the page

v1.8.0

Scheduled CSV exports (Pro) — weekly (Monday 6am) or monthly (1st of month 6am) exports emailed automatically with visitors + page views attached

v1.7.0

Geo-blocking (Pro) — block or redirect visitors by country code before any DB writes; supports skip, 403 block, or redirect
White-label dashboard (Pro) — custom menu label and page title for client sites
Extended data retention (Pro) — set to 0 for unlimited; free plan capped at 90 days

v1.6.0

Traffic spike alerts (Pro) — email alert when page views in the last 15 minutes exceed a configurable multiple of your 7-day baseline
Configurable threshold (default 2×), 1-hour cooldown to prevent spam, test-send from Settings

v1.5.0

Email digests (Pro) — daily and weekly HTML email reports with visit stats, top pages, referrers, and countries
Period-over-period % change — ▲▼ comparison for visits and unique visitors
Configurable digest recipient, schedule, and test-send from Settings
Fixed PHP 7.4 compatibility — replaced str_contains() with strpos()

v1.4.0

UTM campaign tracking (Pro) — captures utm_source, utm_medium, utm_campaign, utm_term, utm_content with last-touch attribution
Campaigns dashboard section (Pro) — sortable table showing top sources, mediums, and campaigns
Automatic DB migration adds UTM columns to existing installs

v1.3.0

Send Message to Visitor (Pro) — message any live visitor; popup delivered in real-time via frontend polling
Session cookie tracking for reliable per-visitor identification
Frontend polling script checks for pending messages every 15 seconds

v1.2.0

Dashboard widget — live visitor stats on the WP admin home screen
Admin bar badge — live visitor count in the toolbar with auto-refresh
Operating Systems breakdown table
Clear All Data button in Settings

v1.1.0

Settings page — configurable data retention, IP exclusion list, IP anonymization
CSV export — download visitors and page views as CSV files

v1.0.0

Initial release — visitor tracking, IP geolocation, admin dashboard, device/browser/OS detection, auto-cleanup

FAQ

Is BT Visitor Insights really free?

The core plugin is free forever with no time limits. A Pro version is available that adds advanced features like email digests, UTM campaign tracking, Send Message to Visitor, and more. See the pricing page for details.

Does it slow down my site?

Minimal impact. Core tracking happens entirely server-side. A small JavaScript file is loaded on front-end pages to support the Send Message feature (polling every 15 seconds for admin messages). There is no measurable impact on page load speed or Core Web Vitals.

Is it GDPR compliant?

BT Visitor Insights is designed to be GDPR-friendly. It stores no cookies, respects Do Not Track headers, auto-purges data after 90 days, and keeps all data on your server. However, since IP addresses are personal data under GDPR, you should disclose the use of this plugin in your privacy policy. Consult a legal professional for full compliance.

How accurate is the geolocation?

City-level accuracy is typical for most visitors. Country-level data is highly reliable. Accuracy may be lower for mobile network users and visitors using VPNs or proxies, where the reported location may reflect the network provider rather than the physical location.

Can I export the data?

Yes. Go to Visitor Insights › Settings and use the Export Data section to download a CSV of all visitors or page views. You can also export directly using phpMyAdmin or WP-CLI — tables are prefixed with your WordPress table prefix followed by btvi_.

Support

If you run into anything that isn't covered here:

Submit a support ticket at boulleytechnology.ca/support.php
Email support at support@boulleytechnology.ca
General inquiries: info@boulleytechnology.ca

License holders get priority response. We typically reply within a few hours during business hours.