VisitorLens Documentation

Everything you need to install, configure, and get the most out of VisitorLens — from basic setup to advanced WooCommerce analytics.

What you can do with VisitorLens

Free vs Pro

Requirements

Installation

Option A — Install from WordPress.org (Recommended)

Option B — Upload ZIP manually

Installing the Pro plugin

First Steps After Installation

Why am I not seeing data?

By default, VisitorLens excludes logged-in WordPress administrators from tracking. This means if you browse your site while logged in as admin, nothing gets recorded. This is intentional — admin visits would pollute your data.

Verify tracking is working

1. Open your site in Incognito mode.
2. Click around a few pages, scroll up and down.
3. Go back to WP Admin → VisitorLens → Dashboard.
4. You should see Visitors, Page Views, and Sessions counters increase.
5. Go to Replay — your session should appear in the list within 30–60 seconds.

Recommended settings to configure first

Dashboard FREE

The Dashboard is your analytics overview. It shows key metrics for the past 30 days (or your selected date range) and updates in real time.

KPI Cards

Charts

• Visitors over time — Daily line chart showing unique visitors and page views.
• Traffic sources — Donut chart: Organic Search, Social, Paid, Referral, Direct.
• Top pages — Table of most visited pages with view counts.
• Recent sessions — List of the latest recorded sessions with device, location, and duration.

Real-time panel

The top-right of the dashboard shows visitors online right now. This counter updates every 60 seconds. A visitor is considered "online" if they've made a tracking request in the last 5 minutes.

Visitor Tracking FREE

VisitorLens automatically tracks visitor data on every page of your site. No shortcodes or manual setup needed.

What data is collected

How sessions are identified

Each visitor gets a unique session key (UUID) stored in sessionStorage. This resets on every new browser tab or session — it is not a persistent cookie.

SPA support

VisitorLens intercepts history.pushState and history.replaceState to track navigation in Single Page Apps (React, Vue, etc.) and WordPress themes that use AJAX-based navigation.

Traffic source classification

Session Replay FREE

Session Replay lets you watch a full visual playback of how a visitor interacted with your site — where they clicked, how they scrolled, what they typed, and where they got stuck.

What gets recorded

Automatic behaviour detection

Viewing a replay

1. Go to VisitorLens → Replay in your WP admin.
2. The session list shows all recordings with date, device, location, duration, page count, and frustration score.
3. Use the filters (device, country, date range, frustration level) to find specific sessions.
4. Click any session row to open the replay player.
5. Use the playback controls: Play/Pause, Speed (0.5× to 4×), and the event timeline at the bottom to jump to specific moments.

Frustration score

Each session gets a frustration score from 0 to 100. It is calculated from:

Session limits (Free)

The free plan records up to 500 sessions per month. When the limit is reached, new sessions are not recorded until the next calendar month. Upgrade to Pro for unlimited recording.

Statistics FREE

The Statistics page gives you deep analytics breakdowns across five tabs: Overview, Pages, Audience, Traffic Sources, and Real-time.

Overview tab

Shows KPI summary cards and a line chart for visitors and page views over your selected date range (7 days, 30 days, 90 days, or custom).

Pages tab

Table of all pages ordered by views. Includes: page URL, views, unique visitors, avg. time on page, and bounce rate.

Audience tab

• Countries — Map and table of visitor countries.
• Browsers — Chrome, Firefox, Safari, Edge breakdown.
• Devices — Desktop vs Mobile vs Tablet split.
• Operating systems — Windows, macOS, iOS, Android, Linux.
• Screen resolutions — Most common viewport sizes.
• Languages — Browser language distribution.

Traffic Sources tab

• Source type breakdown (organic, social, paid, referral, direct).
• Top referrer domains with visit counts.
• Top search engines and most common search keywords.
• UTM campaign performance table.

Real-time tab

Live view of visitors on your site right now. Updates every 30 seconds. Shows active pages and visitor count per page.

Settings FREE

All plugin settings are found at VisitorLens → Settings. Settings are organised into tabs.

General tab

Privacy tab

Tracking tab

Data tab

Data Management FREE

Exporting sessions

Go to VisitorLens → Replay. Click the Export button in the top toolbar. Choose your format:

• CSV — Spreadsheet-friendly. Opens in Excel, Google Sheets.
• JSON — Full session data including all events. For developers.

Export respects your active filters — so you can export only mobile sessions, or only sessions from a specific country.

Bulk deleting sessions

Check the checkboxes next to sessions in the Replay list, then click Delete Selected. Deletion is permanent and immediate.

Storage usage

Go to VisitorLens → Settings → Data to see how much database space VisitorLens is using, broken down by table.

Uninstalling cleanly

Heatmaps PRO

Heatmaps give you a visual overlay on top of your actual pages showing where users interact the most.

Types of heatmaps

Filtering heatmaps

• Filter by device type — desktop and mobile heatmaps are often very different.
• Filter by date range — see how engagement changes after a redesign.
• Filter by traffic source — do organic visitors engage differently than paid?

Funnels & Goals PRO

Funnel tracking lets you define multi-step user journeys and see exactly where visitors drop off.

Creating a funnel

1. Go to VisitorLens → Funnels → Add New Funnel.
2. Give your funnel a name (e.g. "Checkout Flow").
3. Add steps with URL patterns. Example: /cart/ → /checkout/ → /order-received/
4. Save the funnel. Data starts collecting from this point forward.

Reading funnel reports

Each funnel shows:

• Entry count — how many sessions entered step 1.
• Step-by-step drop-off — % who moved from each step to the next.
• Overall conversion rate — % who completed all steps.
• Sessions that dropped — links to actual replays of visitors who left at each step.

Goals

Goals are simpler than funnels — a single URL that counts as a conversion. Example: visiting /thank-you/ = a completed purchase.

Goal reports show daily conversion counts, conversion rate trends, and session-level evidence.

WooCommerce Integration PRO

VisitorLens Pro connects deeply with WooCommerce to give you revenue-level insights tied directly to visitor sessions.

Features

Viewing abandoned carts

1. Go to VisitorLens → WooCommerce → Abandoned Carts.
2. See a list of all abandoned carts with: visitor info, cart value, products, and time of abandonment.
3. Click Watch Replay to see the session where the cart was abandoned.

Core Web Vitals PRO

VisitorLens Pro measures Google's Core Web Vitals on every page — helping you identify performance issues that hurt both user experience and search rankings.

Metrics tracked

Per-page breakdown

Each metric is reported per page URL and by device type (mobile vs desktop). Mobile and desktop vitals are often dramatically different — always check both.

Error & Resource Tracking PRO

VisitorLens Pro automatically captures JavaScript errors and broken resource loads, and links them to session replays so you can see exactly what the user experienced.

What gets tracked

• JavaScript errors — Error message, source file, line number, column, and stack trace.
• Broken images — Images that failed to load (404, permission denied, etc.).
• Broken CSS — Stylesheets that failed to load.
• Broken scripts — JavaScript files that failed to load.

Using error reports

1. Go to VisitorLens → Errors.
2. Errors are grouped by message — so if 50 visitors hit the same JS error, it appears as one group with a count of 50.
3. Click a group to see the list of affected sessions.
4. Click Watch Replay on any session to see the error in context.

Surveys & Feedback PRO

Survey types

Creating a survey

1. Go to VisitorLens → Surveys → Add New.
2. Write your question and answer options (multiple choice or rating 1–5).
3. Choose trigger type and target pages.
4. Set status to Active and save.

Feedback widget

Separate from surveys, the Feedback widget is a persistent button on your site that visitors can click to submit written feedback, categorised as Bug / Feature Request / General. Feedback submissions optionally include a screenshot.

Alerts & Webhooks PRO

Get notified automatically when something important happens on your site — without having to check the dashboard manually.

Alert types

Delivery methods

• Email — Sent to configured recipients. Supports multiple addresses.
• Webhook — POSTs a JSON payload to any URL. Compatible with Slack, Discord, Zapier, Make, and custom endpoints.
• Weekly summary email — A digest of the past week's key metrics, sent every Monday morning.

Webhook payload example

{
  "alert_type": "error_spike",
  "threshold": 10,
  "current_count": 23,
  "time_window": "1h",
  "site_url": "https://yoursite.com",
  "triggered_at": "2026-03-29T14:30:00Z"
}

Team & Collaboration PRO

Invite team members, control what they can see and do, add notes to sessions, and share replays with clients — all from inside WordPress.

Roles & permissions

Adding a team member

1. Go to VisitorLens → Settings → Team.
2. Search for a WordPress user by name or email.
3. Assign a role (Viewer, Analyst, or Admin).
4. Click Add Member. They can immediately access VisitorLens at their permission level.

Session notes & tags

In the Replay player, use the Collaboration panel (right sidebar) to:

• Add notes with timestamps (e.g. "User got confused at the checkout step at 0:42").
• Add tags to categorise sessions (e.g. "checkout-issue", "mobile-bug", "review-needed").

Shareable replay links

Analysts and Admins can generate a public share link for any session replay. Share it with a client or colleague — they can watch the replay in their browser without needing a WordPress account.

Accessibility Insights PRO

VisitorLens Pro tracks how visitors navigate using keyboard-only interaction — a key signal for accessibility compliance and WCAG audit work.

What is tracked

• Tab key presses — How many times the user presses Tab to navigate the page.
• Shift+Tab presses — How many times the user navigates backwards.
• Escape key presses — How often users press Escape (often indicates a confusing modal or overlay).

Keyboard-only sessions

A session is flagged as "keyboard-only" if the visitor used Tab/Shift+Tab for navigation and had very low mouse movement. These are likely screen reader users or keyboard-preference users.

Accessibility struggle signals

Insights Engine PRO

The Insights Engine automatically analyses your session data and surfaces UX problems — you don't have to know what to look for. It does the analysis for you.

Insight categories

Severity levels

• 🔴 Critical — Immediate attention needed. Typically 3× above baseline.
• 🟡 Warning — Worth reviewing. Typically 2× above baseline.
• 🔵 Info — Interesting observation, low urgency.

Session evidence

Every insight links to the specific sessions that triggered it. Click View sessions on any insight to open a filtered replay list showing exactly who experienced the problem.

Privacy & GDPR

VisitorLens is built with privacy first. Here is how each privacy requirement is handled.

Data storage

All data is stored in your own WordPress database. Nothing is sent to VisitorLens servers, third-party analytics platforms, or any external service. You own your data completely.

IP addresses

Raw IP addresses are never stored. The tracker hashes the IP immediately on arrival using a one-way hash. The hash is used for deduplication (unique visitor counting) but cannot be reversed to reveal the original IP.

Consent modes

Consent plugin integration

VisitorLens checks window.vsr_consent before tracking. Your cookie consent plugin should set this to true when analytics consent is granted. Example:

// Call this when the visitor accepts analytics cookies
window.vsr_consent = true;
window.dispatchEvent(new Event('vsr_consent_granted'));

Input masking

When input masking is enabled (recommended), all text typed into <input>, <textarea>, and <select> fields is replaced with * characters in session recordings. Passwords are always masked regardless of this setting.

Do-Not-Track

When "Respect Do-Not-Track" is enabled, VisitorLens checks the browser's DNT: 1 header and skips tracking entirely for those visitors.

Data deletion requests

To delete all data for a specific visitor, use the Replay search to find their sessions (by country, device, or date range), select all, and delete. VisitorLens does not store names or emails by default, so deletion is by session identifier.

REST API Reference

VisitorLens uses the WordPress REST API (namespace: vsr/v1). Base URL: https://yoursite.com/wp-json/vsr/v1/

Free endpoints

Authentication

Admin endpoints require a WordPress nonce. The nonce is automatically injected into the page via wp_localize_script as VSR.nonce. External API calls should use WordPress Application Passwords.

fetch('/wp-json/vsr/v1/stats/overview?range=30', {
  headers: {
    'X-WP-Nonce': VSR.nonce
  }
})

Track endpoint payload

{
  "url":        "/pricing/",
  "referrer":   "https://google.com",
  "browser":    "Chrome",
  "platform":   "Windows",
  "device":     "desktop",
  "screen_w":   1920,
  "screen_h":   1080,
  "lang":       "en-US",
  "tz":         "America/New_York",
  "load_time":  843,
  "utm_source": "google",
  "utm_medium": "cpc"
}

Database Tables

VisitorLens uses its own database tables with the prefix {wp_prefix}vs_. Example: if your WP prefix is wp_, tables are named wp_vs_visitors, etc.

Free plugin tables (13 tables)

Pro plugin tables (17 additional tables)

Troubleshooting

No data appearing in dashboard

• Are you browsing as a logged-in admin? Admins are excluded by default. Test in Incognito mode.
• Is your REST API accessible? Visit https://yoursite.com/wp-json/ — you should see a JSON response.
• Is a security plugin (Wordfence, iThemes Security) blocking /wp-json/vsr/? Add it to the allowlist.
• Is JavaScript loading? Check your browser console for JS errors on the frontend.

Sessions recorded but replay is blank

• The replay player reconstructs the page from recorded events. Very short sessions (< 3s) may not have enough data to render.
• Check that vs_session_events table has rows for the session — if empty, the recorder script may not have loaded.
• CSP (Content Security Policy) headers can block the inline replay reconstruction. Check your browser console for CSP errors.

Deprecation warnings in PHP logs

On WordPress 6.2+, passing null to %f or %d in $wpdb->prepare() triggers a deprecation notice. VisitorLens handles this by defaulting lat/lon to 0.0 and screen dimensions to 0. If you see these warnings, make sure you are on VisitorLens 1.0.1+.

Pro features not showing after activation

• Make sure both the free plugin AND Pro plugin are active. Pro requires the free plugin.
• Check for PHP errors in your server log — a PHP error during Pro activation may prevent features from loading.
• Try deactivating and reactivating the Pro plugin.
• Make sure your PHP version is 7.4+. PHP 7.2 and below are not supported.

WooCommerce orders not linking to sessions

• The link is made within a 6-hour window of the session. If the visitor returned days later to buy, it won't link.
• Guest checkouts link by IP hash. If the visitor's IP changed between browsing and checkout, no link is made.
• Logged-in orders always link by WordPress user ID — these are reliable.

Performance concerns

VisitorLens is designed to be lightweight:

• Tracker scripts are ~8KB gzipped.
• Mouse events throttled to 200ms; scroll to 300ms.
• Events batched into a single request every 8 seconds (max 150 events per batch).
• If you have very high traffic and are concerned about DB load, reduce the Sampling Rate in Settings → General to 50% or lower.

Frequently Asked Questions

Does VisitorLens work on multisite?

Network (multisite) support is on the roadmap. Currently, VisitorLens tracks data per-site but does not aggregate across a multisite network in a single dashboard.

Can I use VisitorLens with a caching plugin?

Yes. VisitorLens tracking happens via JavaScript after the page loads, so page caching doesn't affect data collection. However, make sure your caching plugin doesn't cache the REST API endpoint responses.

How do I exclude my own visits?

Go to Settings → Privacy → Exclude logged-in admins and make sure it's ON. For non-admin visits you want to exclude (e.g. your office's IP), add it to Settings → Tracking → Exclude IPs.

Is VisitorLens compatible with Cloudflare?

Yes. If you use Cloudflare's proxy, make sure the /wp-json/vsr/ path is not cached. Add a Cloudflare Page Rule or Cache Rule to bypass cache for that path.

Can I use VisitorLens alongside Google Analytics?

Absolutely. They serve different purposes — GA is great for aggregate traffic analysis, VisitorLens is for individual session-level UX analysis. Many sites use both.

How do I upgrade from Free to Pro?

Purchase Pro at visitorlens.com. Download the Pro ZIP, upload it via Plugins → Add New → Upload Plugin, and activate. All free plugin data is preserved. Pro features activate immediately.

What happens to my data if I cancel Pro?

Your data stays in your database — VisitorLens never deletes your data on deactivation. You'll lose access to Pro-only features but free features continue working. All recorded sessions remain viewable.

Can I self-host the documentation?

This documentation file (docs.html) is a self-contained static HTML file. Copy it anywhere — no server dependencies required.