dotfiles/.agents/skills/cloudflare-deploy/references/zaraz/gotchas.md

Zaraz Gotchas

Events Not Firing

Check:

1. Tool enabled in dashboard (green dot)
2. Trigger conditions met
3. Consent granted for tool's purpose
4. Tool credentials correct (GA4: G-XXXXXXXXXX, FB: numeric only)

Debug:

zaraz.debug = true;
console.log('Tools:', zaraz.tools);
console.log('Consent:', zaraz.consent.getAll());

Consent Issues

Modal not showing:

// Clear consent cookie
document.cookie = 'zaraz-consent=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;';
location.reload();

Tools firing before consent: Map tool to consent purpose with "Do not load until consent granted".

SPA Tracking

Route changes not tracked:

1. Configure History Change trigger in dashboard
2. Hash routing (#/path) requires manual tracking:

window.addEventListener('hashchange', () => {
  zaraz.track('pageview', { page_path: location.pathname + location.hash });
});

React fix:

const location = useLocation();
useEffect(() => {
  zaraz.track('pageview', { page_path: location.pathname });
}, [location]); // Include dependency

Performance

Slow page load:

• Audit tool count (50+ degrades performance)
• Disable blocking triggers unless required
• Reduce event payload size (<100KB)

Tool-Specific Issues

Tool	Issue	Fix
GA4	Events not in real-time	Wait 5-10 min, use DebugView
Facebook	Invalid Pixel ID	Use numeric only (no fbpx_ prefix)
Google Ads	Conversions not attributed	Include send_to: 'AW-XXX/LABEL'

Data Layer

• Properties persist per page only - set on each page load
• Nested access: {{client.__zarazTrack.user.plan}}

Limits

Resource	Limit
Request size	100KB
Consent purposes	20
API rate	1000 req/sec

When NOT to Use Zaraz

• Server-to-server tracking (use Workers)
• Real-time bidirectional communication
• Binary data transmission
• Authentication flows