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

# 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

'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

'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

'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)

# .env.local
# UMAMI_WEBSITE_ID=

Troubleshooting

Analytics Not Working?

1. Check environment variables:

   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 for detailed documentation
2. Check EXAMPLES.md for more use cases
3. Review analytics-events.ts for event definitions
4. Explore useAnalytics.ts for the hook implementation