Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt

Use this file to discover all available pages before exploring further.

Events not appearing in DATALYR? This guide helps diagnose and fix common tracking issues.

​
Quick Diagnostic

Check Event Stream: Go to Dashboard → Event Stream and look for recent events. If you see events appearing, tracking is working. Common Symptoms:
  • No events in Event Stream
  • Script not loading
  • Events delayed
  • Some pages not tracking

​
Script Not Loading

​
Verify Script Installation

Check Script Tag:
  1. Open your website
  2. Right-click → Inspect (or View Source)
  3. Search for datalyr or dl.js
  4. Verify script tag exists:
<script defer src="https://track.datalyr.com/dl.js"
  data-workspace-id="your_workspace_id">
</script>
Common Issues:
  • Script not in <head> tag
  • Missing data-workspace-id attribute
  • Wrong workspace ID
  • Script removed by page builder/theme update

​
Check Network Tab

Steps:
  1. Open browser DevTools (F12)
  2. Go to Network tab
  3. Reload page
  4. Search for dl.js
What to Look For:
  • Status: 200 (success)
  • Type: script
  • Size: ~15-20KB
Common Problems: 404 Not Found:
  • Script URL incorrect
  • Using old/deprecated URL
  • Typo in script source
Fix: 
<!-- Correct -->
<script defer src="https://track.datalyr.com/dl.js"></script>

<!-- Wrong -->
<script defer src="https://datalyr.com/dl.js"></script>
<script defer src="https://tracking.datalyr.com/dl.js"></script>
Blocked by Ad Blocker:
  • Ad blockers may block tracking scripts
  • Test in incognito mode or different browser
  • See Ad Blocker Workaround below
CORS/CSP Issues:
  • Content Security Policy blocking script
  • Check browser console for CSP errors
  • Add track.datalyr.com to CSP whitelist

​
Check Console Errors

Open Console:
  1. DevTools (F12) → Console tab
  2. Look for errors mentioning DATALYR or dl.js
Common Errors: “workspaceId is required”: 
Error: [Datalyr] workspaceId is required
Fix: Add data-workspace-id attribute to script tag. “Failed to load resource”: Script cannot be loaded from server. Fix: Check internet connection, verify script URL. “datalyr is not defined”: Trying to use SDK before script loads. Fix: Ensure script has defer attribute, or wrap code in load event: 
window.addEventListener('load', function() {
  datalyr.track('event_name');
});

​
Wrong Workspace ID

Symptoms:
  • Script loads but no events appear
  • Events appearing in wrong workspace
Check Workspace ID:
  1. Go to Settings → Tracking Script
  2. Copy workspace ID from script
  3. Compare with ID in your website’s script tag
Fix: Replace workspace ID in your script tag with correct ID from Settings.

​
Events Not Appearing

​
Script Loads But No Events

Enable Debug Mode: Option 1: URL Parameter Add ?dl_debug=true to URL and reload page. Option 2: Console 
localStorage.setItem('dl_debug', 'true');
location.reload();
Check Console: Look for debug logs: 
[Datalyr] SDK initialized
[Datalyr] Event tracked: pageview
[Datalyr] Event queued: pageview
[Datalyr] Flushing 1 events
If No Logs:
  • Script not initialized
  • JavaScript error preventing execution
  • Check console for errors

​
Events Stuck in Queue

Symptoms: Console shows “Event queued” but not “Events sent successfully”. Check Network Tab:
  1. Filter by ingest or track.datalyr.com
  2. Look for POST requests
  3. Check status codes
Common Issues: Network Error: 
Failed to fetch
Causes:
  • Offline/poor connection
  • Firewall blocking requests
  • VPN interfering
Fix: Events queue offline and retry automatically. Check network connection. 401 Unauthorized: Using Server/Mobile SDK with invalid API key. Fix: Verify API key from Settings → API Keys. 429 Too Many Requests: Rate limit exceeded (rare). Fix: Contact [email protected] to increase limits.

​
Specific Page Not Tracking

Single-Page Applications (SPAs): Only first pageview tracked, navigation not tracked. Fix: Enable SPA tracking: 
datalyr.init({
  workspaceId: 'your_workspace_id',
  trackSPA: true  // Auto-track navigation
});
Specific Routes/Pages: Some pages track, others don’t. Possible Causes:
  • Script not on all pages
  • Page loads before script
  • Script blocked on specific pages
Fix:
  • Ensure script in global header/footer (not page-specific)
  • For WordPress: Add to theme’s header.php
  • For Shopify: Add to theme.liquid

​
Platform-Specific Issues

​
Shopify

Symptoms:
  • Tracking works on some pages, not checkout
  • Events missing after theme update
Checkout Tracking: Shopify checkout pages are separate domain. See Shopify Installation. Theme Updates: Script may be removed when updating theme. Fix: Re-add script to theme.liquid after updates.

​
WordPress

Symptoms:
  • Script appears but doesn’t work
  • Conflicts with plugins
Plugin Conflicts: Security or optimization plugins may block tracking. Common Culprits:
  • Wordfence (security)
  • WP Rocket (caching)
  • Autoptimize (optimization)
Fix: Whitelist track.datalyr.com in plugin settings. Caching: Changes not visible due to cache. Fix: Clear cache (plugin + browser), test in incognito mode.

​
Next.js

Symptoms:
  • Script loads but events duplicated
  • Tracking breaks on navigation
Server-Side Rendering: Script may load multiple times. Fix: Use Web SDK with proper initialization: 
// pages/_app.js
import { useEffect } from 'react';
import datalyr from '@datalyr/web';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    if (typeof window !== 'undefined') {
      datalyr.init({
        workspaceId: 'your_workspace_id',
        trackSPA: true
      });
    }
  }, []);

  return <Component {...pageProps} />;
}

​
Webflow

Symptoms:
  • Script in Project Settings but not working
  • Only works on published site
Designer Preview: Script may not load in Webflow Designer. Fix: Test on published site, not Designer preview. Custom Code Placement: Script added to wrong location. Fix: Add to Site Settings → Custom Code → Head Code (not Footer).

​
Ad Blocker Workaround

Problem: Ad blockers block tracking scripts. Solutions: 1. Custom Domain (Enterprise): Use your own domain for tracking script. Contact [email protected] to set up custom domain: 
<script defer src="https://analytics.yourdomain.com/dl.js"></script>
2. First-Party Proxy: Proxy tracking requests through your domain. Example Cloudflare Worker: 
// Proxy /dl.js to track.datalyr.com
addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  if (url.pathname === '/dl.js') {
    url.hostname = 'track.datalyr.com';
    event.respondWith(fetch(url));
  }
});
3. Server-Side Tracking: Use Server SDK to track from backend (not blockable). See Server SDK.

​
Browser Privacy Settings

Do Not Track: DATALYR respects DNT by default (configurable). Check Setting: 
datalyr.init({
  workspaceId: 'your_workspace_id',
  respectDoNotTrack: false  // Disable DNT respect
});
Cookies Disabled: Tracking still works, but visitor identification limited. Safari Intelligent Tracking Prevention (ITP): Cookies expire after 7 days. Impact: Returning visitors treated as new after 7 days. Mitigation: Use identify() to link users after login.

​
Performance Issues

Symptoms:
  • Slow page load
  • Events delayed
  • High memory usage
Script Loading: Script should use defer attribute: 
<script defer src="https://track.datalyr.com/dl.js"></script>
Reduce Batch Size: 
datalyr.init({
  workspaceId: 'your_workspace_id',
  flushInterval: 10000,  // Flush more often
  batchSize: 5           // Smaller batches
});
Disable Fingerprinting: 
datalyr.init({
  workspaceId: 'your_workspace_id',
  enableFingerprinting: false  // Reduce CPU usage
});

​
Testing Checklist

Before Contacting Support:
  1. Check Event Stream
    • Visit site, check Dashboard → Event Stream
    • Look for events within 5-10 seconds
  2. Verify Script
    • View page source, confirm script exists
    • Check Network tab for 200 status
  3. Check Console
    • Enable debug mode
    • Look for errors or warnings
  4. Test in Incognito
    • Rules out ad blockers/extensions
    • Fresh cookies/cache
  5. Try Different Browser
    • Rules out browser-specific issues
  6. Check Workspace
    • Confirm workspace ID matches
    • Verify not viewing wrong workspace

​
Still Not Working?

Contact Support: Email [email protected] with:
  • Website URL
  • Workspace ID
  • Browser and version
  • Screenshots of:
    • Network tab (showing dl.js request)
    • Console tab (errors/debug logs)
    • Your script tag in page source
  • Description of issue
Include Debug Info: Enable debug mode and copy console output.

​
Next Steps

Missing Conversions

Why conversions not tracked

Integration Errors

Fix integration issues

Event Stream

View tracked events

Installation Guide

Re-install tracking