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:**
```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