How to add heatmaps to a WordPress site

A WordPress pricing page can contain navigation, forms, and reusable blocks. Heatmaps combine replay interactions so you can inspect where visitors click and how far they scroll.

In this tutorial, I'll check the existing replay installation, configure a Pricing map, and match its background to the widths represented in the data.

What you'll build

Prerequisites

• A staging WordPress site with permission to upload a custom plugin and edit wp-config.php. This tutorial uses a plugin you control. On managed hosting, confirm that your plan permits those changes.
• WordPress 6.3 or later and PHP 7.4 or later, plus a theme that calls wp_head() and wp_footer(). The executable example was tested on WordPress 6.9.10 and PHP 8.3.33.
• An Amplitude project API key: Settings > Projects > your project > General > Manage next to API Key. Managers and Admins can view it. The browser key is public and limited to the minimum scope needed for ingestion. Keep secret keys out of this plugin.
• The session replay setup, with public Pricing pages and verified masking.
• Heatmap access on an Amplitude Plus, Growth, or Enterprise plan with session replay access. Admins or Managers enable capture; users with View permissions can create heatmaps.

Sign up and compare plans for heatmap access.

1. Check the live replay plugin

Follow the heatmap prerequisites. Confirm that the deployed replay plugin is at least 1.7.0. The project CDN controls versions: inspect the loaded script in browser developer tools to identify the deployed release, rather than inferring a version from the latest package listing.

// Browser Console on the public WordPress page
window.amplitude.getDeviceId();

The Browser SDK and replay plugin manage device-ID alignment together. Keep that integration. Heatmaps use replay interactions; a second package or enabling click autocapture is not required for this step.

2. Enable capture for the project

Open Settings > Organizational Settings > Session Replay Settings. Enable heatmap capture for the test project and verify replay capture and its effective sample rate. Sampling limits the interactions available for maps.

// Optional named marker on the public Pricing page
window.amplitude.track('WordPress Heatmap QA', { page_path: location.pathname });
window.amplitude.flush();

The marker helps locate a visit but does not create heatmap clicks. Interact normally and verify its replay. Capture settings and map availability are separate checks.

3. Match the recorded Pricing URL

Open Heatmaps > + New Heatmap and choose a map type. Begin with All Users and a date range including the test. Use Exact match for a clean published Pricing URL, including its trailing slash. Compare with the captured [Amplitude] Page URL property in Instrumentation Explorer.

// Browser Console: inspect the current URL, then compare with captured Page URL
location.href;

The default Page URL strips the query string but can retain a hash, such as #demo. pathOnly controls when page views fire, not URL-property normalization. Use a broader match deliberately if you want both the base page and hash states; check which URLs it includes.

Docs currently describe approximate initial data requirements of ten pages and about 500 replay clicks per page. Check the current reference, processing, and actual project availability. A small staging test can verify capture without producing a populated map. Don't manufacture bulk traffic to claim a visual pass.

4. Match the background and viewport

Use Change Screenshot > From a Replay, or Add Screenshot > From a Replay when no background exists. Choose the recorded width range and a representative page state. The four documented buckets are over 1440px, 900 to 1440px, 500 to 899px, and under 500px.

// Browser Console: record the width of this visit
window.innerWidth;

Inspect a populated click or scroll overlay against that background. Then narrow segments. If the unsegmented map works but a cohort is empty, check identity alignment and captured traffic in that cohort.

MCP: Ask your coding agent to inspect the project's event taxonomy with the Amplitude MCP server before adding events. Reuse existing names when they describe the same action.

Verify it worked

1. WordPress output: Open the public staging page while logged out. Check that the project loader appears once and its inline initialization follows it. After deployment or configuration changes, purge the relevant page and CDN caches.
2. Network: Confirm an event POST receives HTTP 200 from api2.amplitude.com for US projects or api.eu.amplitude.com for EU projects. Large batches can be compressed; use this check for delivery status.
3. Instrumentation Explorer: Inspect event names, properties, counts, and device_id in the Chrome extension. Compare one action with one expected custom event.
4. User Profiles: Search that device ID in Amplitude and inspect its event stream. The docs describe a delay of ten seconds to one minute. Data > Sources > Ingestion Debugger shows request and event counts, rather than individual event payloads.

Verify the map and background explicitly. Record an empty or unavailable overlay as unverified rather than substituting a replay-upload check.

Troubleshooting

The plugin is active but no SDK loads

Check that AMP_BUILD_API_KEY is defined before wp-settings.php, then inspect the public page source. This plugin uses the front-end enqueue hook, so its SDK is absent from the WordPress login and administration pages.

The script order differs from the example

Check caching and script-optimization exclusions for amp-build-sdk and amp-build-engagement. The project loader and inline initialization must remain together. Check for an earlier installation in a theme, tag manager, or snippet plugin.

Requests are blocked

Check the key, region, browser extensions, and Console. Follow the relevant SDK's CSP and endpoint guidance while preserving your site's security policy.

Autocapture settings differ from the file

Review Data > Settings > Autocapture. When remote configuration is enabled, remote values take precedence for the features they specify.

FAQ

Does click autocapture supply heatmap data?

Heatmaps use session replay interactions. Analytics element-interaction tracking is a separate setting.

Can an empty map coexist with a playable replay?

Check capture settings, processing, URL filters, viewport bucket, and available data. A playable replay alone does not prove a populated aggregate map.

Full code reference

Unchanged from earlier pages; keep your versions: amplitude-build.php, analytics.js, demo.php, events.js, engagement.php, experiment-consent.js. Merge the changes into existing files; preserve sibling additions named in the comments.

// No new SDK code. Preserve every existing plugin file.
window.amplitude.track('WordPress Heatmap QA', { page_path: location.pathname });
window.amplitude.flush();

Hand it to your agent

Point your agent at https://amplitude.com/build/wordpress-heatmaps.

Agent task: WordPress heatmaps.
Preserve all WordPress plugin files, privacy, and consent. Verify deployed replay version, project capture settings, recorded Page URL, trailing slash and hash matching, data availability, and viewport bucket. Inspect a populated overlay and actual replay background. Do not infer a visual pass from SDK uploads or generate bulk synthetic traffic.

What this unlocks

Product analytics measures the accepted-form outcome when Demo Form Accepted is installed.

Session replay shows the interaction around the test form after capture and masking are verified.

Web Experiment can use Demo Form Accepted as a conversion metric.

Guides and surveys can ask a visitor what they need on Pricing after targeting is configured.

Next steps