Troubleshooting Guide

Symptoms: No events showing in dashboard, browser console shows 404 error for sp.js

Solution:

1. Verify the script URL is exactly: https://referscope.app/sp.js
2. Check your domain's Content Security Policy (CSP) allows the script (script-src https://referscope.app) and the visits it sends (connect-src https://collect.referscope.app https://referscope.app)
3. If using a CDN or build system, ensure the script isn't being stripped out during build

Symptoms: Script loads successfully but no events in dashboard

Solution:

1. Verify your API key is correct by checking Settings
2. Wait 10-30 seconds after visiting your site - events can take a moment
3. Try sending a test event from your dashboard to verify the connection
4. Check if you're blocking yourself with an ad blocker (disable for your own domain)

Symptoms: Works in development but not in production, or events duplicated on every page change

Solution for Next.js App Router:

1. Add script to app/layout.tsx inside the <head> using Next.js Script component with strategy="afterInteractive"
2. Make sure it's in the root layout, not individual page components
3. Clear .next build cache and rebuild: rm -rf .next && npm run build

Solution for Next.js Pages Router:

1. Add script to pages/_document.tsx in the <Head> component
2. Use regular script tag, not Next.js Script component in _document

Symptoms: Can't find where to add the script, or script gets removed after updates

Solution:

1. Install the "Insert Headers and Footers" plugin or similar code injection plugin
2. Paste the Referscope script in the header section
3. Alternatively, edit your theme's header.php and add the script before </head>
4. For child themes: make sure you're editing the child theme, not parent
5. Clear WordPress cache (if using a caching plugin like WP Super Cache)

Symptoms: Events tracked inconsistently or not at all

Solution:

1. Referscope is privacy-first and doesn't use cookies, so most ad blockers allow it
2. If your ad blocker is aggressive, whitelist referscope.app
3. Test in an incognito window without extensions to verify script works