klz-cables.com/components/analytics/QUICK_REFERENCE.md

# Umami Analytics Quick Reference

## Setup Checklist

- [ ] Add `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
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
# UMAMI_WEBSITE_ID=
```

## Troubleshooting

### Analytics Not Working?

1. **Check environment variables:**

   ```bash
   echo $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