Troubleshooting

Solutions to common EngageTrack issues and how to debug tracking problems.

Troubleshooting

This guide covers the most common issues and how to diagnose them.

Enable Debug Mode

The first step for any tracking issue is to enable debug mode. Add data-debug="true" to your script tag:

<script
	defer
	data-site-id="YOUR_SITE_ID"
	data-debug="true"
	src="https://cdn.engagetrack.net/sdk.js"
></script>

Open your browser's developer console (F12 or Cmd+Option+I). You will see detailed logs prefixed with [EngageTrack] for every action the SDK takes.

Script Not Loading

Symptoms: No [EngageTrack] messages in the console. The script file returns a network error.

Check Content Security Policy (CSP)

If your site uses a Content Security Policy, make sure it allows the EngageTrack domains:

Content-Security-Policy:
  script-src 'self' https://cdn.engagetrack.net;
  connect-src 'self' https://api.engagetrack.net;

Check the console for CSP violation errors (they appear as red error messages mentioning "Content Security Policy").

Check for Ad Blockers

Ad blockers may block cdn.engagetrack.net or api.engagetrack.net. To verify:

Disable your ad blocker temporarily
Reload the page
If tracking works, set up a proxy to serve the script from your own domain

Verify the Script Tag

Make sure the script tag is correct:

The src URL is https://cdn.engagetrack.net/sdk.js
The data-site-id attribute is present and not empty
The defer attribute is included (the script needs the DOM to be ready)
The script is in the <head> section

No Data in Dashboard

Symptoms: The script loads and debug logs appear, but no data shows in the dashboard.

Wrong Site ID

The data-site-id in your script tag must match the site ID in your EngageTrack dashboard. Copy it from Site Settings -> General.

Domain Mismatch

If you have an allowed hostnames list configured in Site Settings -> Tracking, the domain your site is served from must be in that list. Check that:

localhost is included if you are testing locally
The exact hostname matches (e.g., www.example.com and example.com are different)

Events Blocked Server-Side

Check the Network tab in your browser's developer tools:

Filter by event to find the POST request to the event endpoint
If the response is 403, your IP may be excluded or the site ID is invalid
If the response is 429, you have hit a rate limit

New events typically appear in the dashboard within 5-10 seconds. If you are looking at the Real-time view, make sure you have selected the correct site from the dropdown.

Revenue Not Appearing

Symptoms: Purchases happen but no revenue data shows in the Revenue dashboard.

Verify Webhook URL

Each payment provider requires a webhook to send purchase events to EngageTrack:

Go to Site Settings -> Revenue
Check that your provider is connected and the webhook URL is configured
For Stripe, the connection is automatic via OAuth. For other providers, verify the webhook URL is set in the provider's dashboard.

Check Metadata (Stripe)

For Stripe integrations, the engagetrack_visitor_id must be included in the checkout session metadata for direct attribution:

const session = await stripe.checkout.sessions.create({
	metadata: {
		engagetrack_visitor_id: visitorId,
	},
	// ...
});

Without this metadata, EngageTrack falls back to email-based or session-based attribution, which may not match all purchases.

Provider Webhook Logs

Check your payment provider's webhook delivery logs for failed deliveries:

Stripe: Dashboard -> Developers -> Webhooks -> Select endpoint -> Recent deliveries
Lemon Squeezy: Settings -> Webhooks -> Click the webhook -> Delivery attempts
Paddle: Developer Tools -> Notifications -> Event log
Polar: Settings -> Webhooks -> Delivery history

Revenue data may take up to 60 seconds to appear after a webhook is received, as the backend processes attribution asynchronously.

Cross-Domain Tracking Not Working

Symptoms: Visitors get a new visitor ID when navigating between domains.

Check Allowed Hostnames

Verify that data-allowed-hostnames includes the destination domain on the source site:

<!-- This must be on the SOURCE domain -->
<script
	defer
	data-site-id="YOUR_SITE_ID"
	data-allowed-hostnames="destination.com"
	src="https://cdn.engagetrack.net/sdk.js"
></script>

Check URL Parameters

When you click a link to the destination domain, the URL should include _et_vid and _et_sid parameters. If they are missing:

Enable debug mode on the source domain
Click the cross-domain link
Look for [EngageTrack] Cross-domain link decorated: in the console
If this log does not appear, the destination hostname is not in the allowed list

Same Site ID

Both domains must use the same data-site-id for the sessions to be stitched together.

See the full Cross-Domain Tracking guide for setup details.

Real-Time Dashboard Not Updating

Symptoms: The real-time view shows stale data or "0 current visitors" despite active traffic.

WebSocket Connection

The real-time dashboard uses WebSocket connections. Check for issues:

Open the Network tab and filter by "WS" (WebSocket)
You should see an active WebSocket connection to the API
If the connection fails, check that your network/firewall allows WebSocket connections

Browser Tab Focus

Some browsers throttle background tabs, which can delay WebSocket messages. Make sure the dashboard tab is in the foreground.

Proxy Configuration

If you are using a reverse proxy (Nginx, Cloudflare), ensure it supports WebSocket upgrades:

# Nginx WebSocket support
location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Self-Visits Inflating Data

Symptoms: Your own visits are being counted, inflating pageview and visitor numbers.

Exclude yourself using one of these methods:

// Run this in the browser console on your tracked site
window.engagetrack.ignore();
// Then reload the page

Or exclude your IP address in Site Settings -> Tracking -> Excluded IPs.

See Exclude Visits for all exclusion options.

Debugging Checklist

If you are still stuck, work through this checklist:

Script loads? Check the Network tab for the SDK request. Status should be 200.
SDK initializes? With data-debug="true", look for [EngageTrack] Initialized with site: in the console.
Events sent? In the Network tab, filter by the event endpoint URL. Check that POST requests are being made.
Events accepted? The event endpoint should return a 200 or 202 status. Any other status indicates a problem.
Correct site? Compare the site_id in the request payload with the site ID in your dashboard.
Not excluded? Check that localStorage.engagetrack_ignore is not set to "true".
Dashboard filters? Make sure no filters are active in the dashboard that would hide your data.

If none of the above resolves your issue, reach out to support with the following details: your site ID, the debug console output, and a screenshot of the Network tab showing the event request and response.