Configure and integrate Heatlens

1. Create a first campaign
2. Configure consent
3. Mask private data
4. Verify the first recording
5. Advanced integrations — optional

This guide starts after plugin installation. The standard path covers a first campaign, consent, masking and collection checks. JavaScript and CSS integrations at the end of the page are optional.

Create a first campaign

After installation, start with a test page containing only fictitious data. Prepare the next two steps (consent and masking) before permitting collection.

1. In the correct Matomo site, open Heatmaps → Manage heatmaps → Create a heatmap.
2. Give the campaign a recognizable name and target the test page. Test its URL in the form: it should match. Do not use private query parameters in this example.
3. Set 100% sampling, a small cap (such as 20 pages), automatic snapshot capture and consent required. Keep the other defaults for this first test.
4. Save the campaign. An eligible visit after consent will capture the snapshot; entering a URL does not trigger a remote capture.

The settings reference explains URL rules, quotas and devices.

Configure consent

Campaigns require explicit heatmap consent by default. With Matomo requireConsent, grant tracking consent only after visitor agreement and revoke it on withdrawal:

_paq.push(['requireConsent']);
_paq.push(['setConsentGiven']);
// On withdrawal:
_paq.push(['forgetConsentGiven']);

For separate heatmap consent use:

_paq.push(['Heatlens.setConsentGiven']);
// When heatmap consent is withdrawn:
_paq.push(['Heatlens.forgetConsentGiven']);

These calls use the same Matomo queue. They do not override Matomo opt-out or a missing tracking consent. Cookie consent alone is insufficient. Disabling the campaign consent requirement changes this behavior: review your policy before doing so.

Mask private data

Form controls, editable content and elements marked data-heatlens-mask, data-matomo-mask or data-matomo-ignore are masked in the visitor browser. Add campaign-specific hidden selectors and explicitly mark private text outside forms. Email/long-number masking cannot identify all personal information.

Example of a region to mask before capture:

<div data-heatlens-mask>Customer name and address</div>

Verify the first recording

The plugin should have passed the installation check. Use the campaign and test page prepared above.

1. In a test browser, refuse then grant consent: Heatlens must not collect before the required consent. After accepting, click, move and scroll, then wait a few seconds.
2. Open the report for today or all retained dates, with no segment and the correct device and revision. Expect at least one page view, a snapshot and points for the interactions performed.
3. Check masking with fictitious data, JSON/PNG exports and collection stopping after withdrawal.
4. Delete only this test campaign when finished. Adapt targeting, caps and sampling for your real campaigns to your needs.

If a result is missing, follow troubleshooting by symptom. For day-to-day report reading, continue to the user guide.

Advanced integrations — optional

These options are for sites that need them. They are not required to start an automatically captured heatmap on a conventional page.

Single-page applications (SPA)

For SPAs, keep one Matomo virtual page view per route:

_paq.push(['setCustomUrl', location.href]);
_paq.push(['trackPageView']);

For unusually late rendering, Heatlens.trackPageView can restart capture after rendering. Do not routinely call it in addition to every native page view or on every component update.

JavaScript trigger

Before the first page view, configure the trigger in the website code:

_paq.push(['Heatlens.setTrigger', function (campaign) {
    return campaign.id !== 42 || window.analyticsAudienceReady === true;
}]);

Replace 42 with the campaign ID whose audience condition you want to check. The synchronous callback receives id, revision and sanitized URL. Only true allows collection. False, exceptions and Promises deny it. Interactions, flushes and SPA pages recheck the condition; denied pending events are discarded. Pass null to remove the callback. Consent, opt-out, targeting, sampling and quotas still apply. A browser condition is not server authorization.

Manual capture

Select Manual under advanced Snapshot capture options. Once consent has been granted and collection has started on an eligible page, prepare the desired state (open menu, loaded content), then run on the measured page:

_paq.push(['Heatlens.captureSnapshot', HEATMAP_ID]);

The dot denotes a Matomo tracker method. For diagnostics, Matomo.getAsyncTrackers()[0].Heatlens.captureSnapshot(HEATMAP_ID) returns true when queued, not when acknowledged by the server. false means no eligible current collection (consent, targeting, sampling, quota, or config still loading). Wait until collection starts before calling. Reference URL, masking and revision checks still apply. Existing snapshots are never overwritten: create a new revision, reload the page or send its next Matomo page view, then capture again. Wait for media to load; unavailable images can become placeholders.

Rendering styles

Prefix rendering-only rules in accessible website stylesheets with html.heatlens:

html.heatlens .cookie-banner { display: none; }
@media (max-width: 700px) { html.heatlens .content { font-size: 18px; } }

The visitor page is never assigned this class. Allowed declarations and structural element identities are stored, applied to the report and PNG, and follow the selected width/media queries. Retake the snapshot after changes. Imports, external resources, variables and complex selectors remain unsupported. Rendering styles never replace privacy masking: hiding content in a report does not remove captured content.

See also rendering limits.