update skills

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

@@ -0,0 +1,81 @@
+# 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:**
+```javascript
+zaraz.debug = true;
+console.log('Tools:', zaraz.tools);
+console.log('Consent:', zaraz.consent.getAll());
+```
+
+## Consent Issues
+
+**Modal not showing:**
+```javascript
+// 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:
+```javascript
+window.addEventListener('hashchange', () => {
+  zaraz.track('pageview', { page_path: location.pathname + location.hash });
+});
+```
+
+**React fix:**
+```javascript
+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