WPMC Behavior & Heatmap — Overview & Docs

Tables (with {$wpdb->prefix}): wpmc_clicks, wpmc_mouse_trails, wpmc_sessions, wpmc_views

clicks schema

id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
session_id VARCHAR(255) NOT NULL,
page_url VARCHAR(255) NOT NULL,
target_label TEXT DEFAULT NULL,
target_selector TEXT DEFAULT NULL,
target_selector_fallback TEXT DEFAULT NULL,
offset_x INT DEFAULT NULL,
offset_y INT DEFAULT NULL,
viewport_x INT DEFAULT NULL,
viewport_y INT DEFAULT NULL,
scroll_x INT DEFAULT NULL,
scroll_y INT DEFAULT NULL,
link_url TEXT DEFAULT NULL,
action_type ENUM('click','navigation') NOT NULL DEFAULT 'click',
device_type ENUM('desktop','mobile') NOT NULL DEFAULT 'desktop',
post_type VARCHAR(20) DEFAULT NULL,
semantic_type VARCHAR(30) DEFAULT NULL,
semantic_subtype VARCHAR(30) DEFAULT NULL,
semantic_area VARCHAR(30) DEFAULT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
window_width INT DEFAULT NULL,
window_height INT DEFAULT NULL,
target_width INT DEFAULT NULL,
target_height INT DEFAULT NULL,
context_selector TEXT DEFAULT NULL,
label_hash CHAR(32) DEFAULT NULL,
PRIMARY KEY (id)

views schema

id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
session_id VARCHAR(255) NOT NULL,
user_id VARCHAR(255) NOT NULL,
page_url VARCHAR(255) NOT NULL,
referrer_type ENUM('Direct','Internal','External') DEFAULT 'Direct',
referrer_url TEXT,
device_type ENUM('desktop','mobile') DEFAULT 'desktop',
duration_seconds INT DEFAULT NULL,
scroll_depth TINYINT DEFAULT NULL,
post_type VARCHAR(20) DEFAULT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
INDEX idx_session_user (session_id, user_id)

sessions schema

session_id VARCHAR(64) NOT NULL,
user_id VARCHAR(64) NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
end_time DATETIME DEFAULT NULL,
last_activity DATETIME DEFAULT NULL,
device_type ENUM('desktop','mobile') DEFAULT 'desktop',
referrer_type ENUM('Direct','Internal','External') DEFAULT 'Direct',
referrer_url TEXT,
user_agent TEXT,
PRIMARY KEY (session_id)

mouse schema

id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
session_id VARCHAR(255) NOT NULL,
page_url VARCHAR(255) NOT NULL,
trail LONGTEXT NOT NULL,
device_type ENUM('desktop','mobile') DEFAULT 'desktop',
window_width INT DEFAULT NULL,
window_height INT DEFAULT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
INDEX idx_session_page (session_id, page_url)

Notes: wpmc_sessions.last_activity ensured/added on activation; legacy columns cleaned (e.g., removed from clicks). Indices present for session/user and session+page.

Files: tracking-core.js, user-id-sync.js, inject-clicks.js, preview injectors.

• User ID sync: creates/validates UUID-like wpmc_user_id, persists to localStorage and cookie (2y), exposes window.wpmc.user_id .
• Session management: short-lived wpmc_session + wpmc_session_ts cookies (30 min inactivity timeout) .
• Page view: AJAX wpmc_extended_save_view with session_id, user_id, page_url, referrer, device_type .
• Scroll depth: thresholds [25, 50, 75, 100] → wpmc_extended_save_view_scroll .
• View duration: beforeunload beacon posts wpmc_track_duration (seconds) .
• Admin-user guard: disabled when wpmc_ajax.is_admin_user/wpmc_extended_ajax.is_admin_user .

Files: heatmap-loader.php, iframe-render.php, panel-above-iframe.php (+ mobile variants).

• Tracked page loads in an <iframe> with module scripts to inject dots.
• Colors configurable (click/nav/CTA); saved via nonce-protected form.
• Data posted into iframe and injected by inject-clicks.js; mobile uses delayed injection.

• Menu/pages: wpmc-dashboard, wpmc-clicks-map, wpmc-statistics, wpmc-clicks-settings, wpmc-about, wpmc-data-cleaning.
• List & Details: open details for a specific URL from Heatmap Page List.
• Details navigation: prev/next between pages; search by title in floating panel .
• Tabs: Desktop/Mobile switcher; Click Map vs Referral Sources with .active class .
• Online users: header counter, updates every 30s via AJAX .
• Data reset: per-page wipe (clicks+views) via wpmc_reset_data with nonce .

Bootstrap: chart-init.js binds canvases and fetches JSON via wpmc_chart_nonce and date range .

Endpoints (selection): wpmc_chart_device_type, _referrals, _timespent, _top_pages, _users, _views, wpmc_get_mouse_trajectories, wpmc_get_online_users, wpmc_get_online_users_count, wpmc_reset_data, wpmc_extended_save_view, wpmc_extended_save_view_scroll, wpmc_track_duration.

Chart types: views & users over time (line), Top-10 pages (bar), referrals over time (multi-series), device type (doughnut), time-spent distribution (horizontal bar) .

Alternate loader: chart-scripts.js → wpmc_get_chart_data for simpler views-over-time .

• All chart endpoints verify wpmc_chart_nonce and log rejects.
• Admin actions (wpmc_reset_data, wpmc_get_online_users_count) require admin nonces.
• Tracking endpoints sanitize inputs (wpmc_extended_save_view, _scroll, wpmc_track_duration).

Nonces: wpmc_admin_ajax_nonce, wpmc_chart_nonce, wpmc_extended_nonce, wpmc_heatclick_nonce, wpmc_nonce, wpmc_reset_nonce.

• On public requests (with wpmc_user_id), server updates last_activity in wpmc_sessions.
• Online = distinct user_id with activity in last 5 minutes (configurable to 30) .

• Admin panel for color settings and general options (wpmc-clicks-settings, etc.).
• Heatmap color presets & pickers (see panel-above-iframe.php).

• Minimal writes per event; batched clicks.
• DB indices on session/user and session/page.
• Charts query aggregated (daily) and limited top lists.

• Extra referrer_type buckets, custom device types.
• Export/cleanup via WP-Cron.
• REST mirrors for charts (in addition to AJAX).

• Activation creates/updates tables; cleans legacy fields; ensures required columns.
• Upgrades perform non-destructive schema adjustments.

• Charts empty: ensure wpmc_chart_nonce is localized and date range returns rows; admins may be excluded.
• Online users “—”: check admin nonce and wpmc_user_id cookie on public pages.
• Heatmap not injecting: enqueue module scripts in iframe; ensure click data exists for selected date/device.