umami

components/analytics/QUICK_REFERENCE.md

@@ -0,0 +1,166 @@
+# Umami Analytics Quick Reference
+
+## Setup Checklist
+
+- [ ] Add `NEXT_PUBLIC_UMAMI_WEBSITE_ID` to `.env` file
+- [ ] Verify `UmamiScript` is in your layout
+- [ ] Verify `AnalyticsProvider` is in your layout
+- [ ] Test in development mode
+- [ ] Check Umami dashboard for data
+
+## Environment Variables
+
+```bash
+# Required
+NEXT_PUBLIC_UMAMI_WEBSITE_ID=59a7db94-0100-4c7e-98ef-99f45b17f9c3
+
+# Optional (defaults to https://analytics.infra.mintel.me/script.js)
+NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://analytics.infra.mintel.me/script.js
+```
+
+## Quick Usage Examples
+
+### Track an Event
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function MyComponent() {
+  const { trackEvent } = useAnalytics();
+
+  const handleClick = () => {
+    trackEvent(AnalyticsEvents.BUTTON_CLICK, {
+      button_id: 'my-button',
+      page: 'homepage',
+    });
+  };
+
+  return <button onClick={handleClick}>Click Me</button>;
+}
+```
+
+### Track a Pageview
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function MyComponent() {
+  const { trackPageview } = useAnalytics();
+
+  const navigate = () => {
+    trackPageview('/custom-path');
+    // Navigate...
+  };
+
+  return <button onClick={navigate}>Go to Page</button>;
+}
+```
+
+### Track E-commerce Events
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ProductCard({ product }) {
+  const { trackEvent } = useAnalytics();
+
+  const addToCart = () => {
+    trackEvent(AnalyticsEvents.PRODUCT_ADD_TO_CART, {
+      product_id: product.id,
+      product_name: product.name,
+      price: product.price,
+    });
+  };
+
+  return <button onClick={addToCart}>Add to Cart</button>;
+}
+```
+
+## Common Events
+
+| Event | When to Use | Example Properties |
+|-------|-------------|-------------------|
+| `pageview` | Page loads | `{ url: '/products/123' }` |
+| `button_click` | Button clicked | `{ button_id: 'cta', page: 'homepage' }` |
+| `form_submit` | Form submitted | `{ form_id: 'contact', form_name: 'Contact Us' }` |
+| `product_view` | Product page viewed | `{ product_id: '123', price: 99.99 }` |
+| `product_add_to_cart` | Add to cart | `{ product_id: '123', quantity: 1 }` |
+| `search` | Search performed | `{ search_query: 'cable', results: 42 }` |
+| `user_login` | User logged in | `{ user_email: 'user@example.com' }` |
+| `error` | Error occurred | `{ error_message: 'Something went wrong' }` |
+
+## Testing
+
+### Development Mode
+
+In development, you'll see console logs:
+
+```
+[Umami] Tracked event: button_click { button_id: 'my-button' }
+[Umami] Tracked pageview: /products/123
+```
+
+### Disable Analytics (Development)
+
+```bash
+# .env.local
+# NEXT_PUBLIC_UMAMI_WEBSITE_ID=
+```
+
+## Troubleshooting
+
+### Analytics Not Working?
+
+1. **Check environment variables:**
+   ```bash
+   echo $NEXT_PUBLIC_UMAMI_WEBSITE_ID
+   ```
+
+2. **Verify script is loading:**
+   - Open DevTools → Network tab
+   - Look for `script.js` request
+   - Check Console for errors
+
+3. **Check Umami dashboard:**
+   - Log into Umami
+   - Verify website ID matches
+   - Check if data is being received
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| No data in Umami | Check website ID and script URL |
+| Events not tracking | Verify `useAnalytics` hook is used |
+| Script not loading | Check network connection, CORS |
+| Wrong data | Verify event properties are correct |
+
+## Performance Tips
+
+1. **Use `useCallback` for event handlers** to prevent unnecessary re-renders
+2. **Debounce high-frequency events** (like search input)
+3. **Don't track every interaction** - focus on meaningful events
+4. **Use environment variables** to disable analytics in development
+
+## Privacy & Compliance
+
+- ✅ Don't track PII (personally identifiable information)
+- ✅ Don't track sensitive data (passwords, credit cards)
+- ✅ Follow GDPR and other privacy regulations
+- ✅ Use anonymized IDs where possible
+- ✅ Provide cookie consent if required
+
+## Next Steps
+
+1. Read [`README.md`](README.md) for detailed documentation
+2. Check [`EXAMPLES.md`](EXAMPLES.md) for more use cases
+3. Review [`analytics-events.ts`](analytics-events.ts) for event definitions
+4. Explore [`useAnalytics.ts`](useAnalytics.ts) for the hook implementation