) => {
+ setFormData(prev => ({
+ ...prev,
+ [e.target.name]: e.target.value,
+ }));
+ };
+
+ return (
+
+ );
+}
+```
+
+### Newsletter Signup
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function NewsletterSignup() {
+ const { trackEvent } = useAnalytics();
+
+ const handleSubscribe = (email: string) => {
+ trackEvent(AnalyticsEvents.NEWSLETTER_SUBSCRIBE, {
+ email: email,
+ source: 'footer',
+ newsletter_type: 'weekly',
+ });
+
+ // Subscribe to newsletter
+ // subscribeToNewsletter(email);
+ };
+
+ return (
+
+
+
+
+ );
+}
+```
+
+### Quote Request Form
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function QuoteRequestForm() {
+ const { trackEvent } = useAnalytics();
+
+ const handleSubmit = (formData: FormData) => {
+ trackEvent(AnalyticsEvents.QUOTE_REQUEST, {
+ form_id: 'quote-request',
+ product_type: formData.get('product_type'),
+ quantity: formData.get('quantity'),
+ company_size: formData.get('company_size'),
+ urgency: formData.get('urgency'),
+ });
+
+ // Submit quote request
+ // submitQuoteRequest(formData);
+ };
+
+ return (
+
+ );
+}
+```
+
+---
+
+## User Authentication
+
+### Login Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function LoginForm() {
+ const { trackEvent } = useAnalytics();
+
+ const handleLogin = async (email: string, password: string) => {
+ try {
+ // Track login attempt
+ trackEvent(AnalyticsEvents.USER_LOGIN, {
+ user_email: email,
+ login_method: 'email',
+ login_status: 'attempt',
+ });
+
+ // Perform login
+ // await login(email, password);
+
+ // Track successful login
+ trackEvent(AnalyticsEvents.USER_LOGIN, {
+ user_email: email,
+ login_method: 'email',
+ login_status: 'success',
+ });
+ } catch (error) {
+ // Track failed login
+ trackEvent(AnalyticsEvents.USER_LOGIN, {
+ user_email: email,
+ login_method: 'email',
+ login_status: 'failed',
+ error_message: error.message,
+ });
+ }
+ };
+
+ return (
+
+ );
+}
+```
+
+### Signup Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function SignupForm() {
+ const { trackEvent } = useAnalytics();
+
+ const handleSignup = (userData: {
+ email: string;
+ name: string;
+ company?: string;
+ }) => {
+ trackEvent(AnalyticsEvents.USER_SIGNUP, {
+ user_email: userData.email,
+ user_name: userData.name,
+ company: userData.company,
+ signup_method: 'email',
+ signup_source: 'homepage',
+ });
+
+ // Perform signup
+ // signup(userData);
+ };
+
+ return (
+
+ );
+}
+```
+
+---
+
+## Search & Filtering
+
+### Search Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function SearchBar() {
+ const { trackEvent } = useAnalytics();
+ const [query, setQuery] = useState('');
+
+ const handleSearch = () => {
+ trackEvent(AnalyticsEvents.SEARCH, {
+ search_query: query,
+ search_results_count: 42, // You'd get this from your search results
+ search_filters: {
+ category: 'cables',
+ voltage: 'high',
+ },
+ });
+
+ // Perform search
+ // performSearch(query);
+ };
+
+ return (
+
+ setQuery(e.target.value)}
+ placeholder="Search products..."
+ />
+
+
+ );
+}
+```
+
+### Filter Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ProductFilters() {
+ const { trackEvent } = useAnalytics();
+ const [filters, setFilters] = useState({
+ category: '',
+ voltage: '',
+ material: '',
+ });
+
+ const handleFilterChange = (filterType: string, value: string) => {
+ const newFilters = {
+ ...filters,
+ [filterType]: value,
+ };
+
+ trackEvent(AnalyticsEvents.FILTER_APPLY, {
+ filter_type: filterType,
+ filter_value: value,
+ filter_count: Object.values(newFilters).filter(Boolean).length,
+ all_filters: newFilters,
+ });
+
+ setFilters(newFilters);
+ // Apply filters
+ // applyFilters(newFilters);
+ };
+
+ const handleClearFilters = () => {
+ trackEvent(AnalyticsEvents.FILTER_CLEAR, {
+ previous_filters: filters,
+ });
+
+ setFilters({
+ category: '',
+ voltage: '',
+ material: '',
+ });
+ // Clear filters
+ // clearFilters();
+ };
+
+ return (
+
+
+
+
+
+ );
+}
+```
+
+---
+
+## Content Tracking
+
+### Blog Post View
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+interface BlogPost {
+ id: string;
+ title: string;
+ category: string;
+ author: string;
+}
+
+function BlogPostPage({ post }: { post: BlogPost }) {
+ const { trackEvent } = useAnalytics();
+
+ useEffect(() => {
+ trackEvent(AnalyticsEvents.BLOG_POST_VIEW, {
+ post_id: post.id,
+ post_title: post.title,
+ post_category: post.category,
+ post_author: post.author,
+ });
+ }, [post]);
+
+ return (
+
+ {post.title}
+ By {post.author}
+ {/* Post content */}
+
+ );
+}
+```
+
+### Video Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function VideoPlayer({ videoId, videoTitle }) {
+ const { trackEvent } = useAnalytics();
+
+ const handlePlay = () => {
+ trackEvent(AnalyticsEvents.VIDEO_PLAY, {
+ video_id: videoId,
+ video_title: videoTitle,
+ });
+ };
+
+ const handlePause = () => {
+ trackEvent(AnalyticsEvents.VIDEO_PAUSE, {
+ video_id: videoId,
+ video_title: videoTitle,
+ });
+ };
+
+ const handleComplete = () => {
+ trackEvent(AnalyticsEvents.VIDEO_COMPLETE, {
+ video_id: videoId,
+ video_title: videoTitle,
+ });
+ };
+
+ return (
+
+ );
+}
+```
+
+### Download Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function DownloadButton({ fileName, fileType, fileSize }) {
+ const { trackEvent } = useAnalytics();
+
+ const handleDownload = () => {
+ trackEvent(AnalyticsEvents.DOWNLOAD, {
+ file_name: fileName,
+ file_type: fileType,
+ file_size: fileSize,
+ download_source: 'product-page',
+ });
+
+ // Trigger download
+ // window.location.href = `/downloads/${fileName}`;
+ };
+
+ return (
+
+ );
+}
+```
+
+---
+
+## Error Tracking
+
+### Error Boundary
+
+```tsx
+'use client';
+
+import { Component, ErrorInfo, ReactNode } from 'react';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+interface ErrorBoundaryProps {
+ children: ReactNode;
+ fallback?: ReactNode;
+}
+
+class ErrorBoundary extends Component {
+ state = { hasError: false, error: null };
+
+ static getDerivedStateFromError(error: Error) {
+ return { hasError: true, error };
+ }
+
+ componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+ const { trackEvent } = useAnalytics();
+
+ trackEvent(AnalyticsEvents.ERROR, {
+ error_message: error.message,
+ error_stack: error.stack,
+ error_component: errorInfo.componentStack,
+ error_type: error.name,
+ });
+ }
+
+ render() {
+ if (this.state.hasError) {
+ return this.props.fallback ?? Something went wrong.
;
+ }
+
+ return this.props.children;
+ }
+}
+
+// Usage
+function App() {
+ return (
+
+
+
+ );
+}
+```
+
+### API Error Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ApiClient() {
+ const { trackEvent } = useAnalytics();
+
+ const fetchData = async (endpoint: string) => {
+ try {
+ const response = await fetch(endpoint);
+
+ if (!response.ok) {
+ trackEvent(AnalyticsEvents.API_ERROR, {
+ endpoint: endpoint,
+ status_code: response.status,
+ error_message: response.statusText,
+ });
+
+ throw new Error(`HTTP ${response.status}`);
+ }
+
+ trackEvent(AnalyticsEvents.API_SUCCESS, {
+ endpoint: endpoint,
+ status_code: response.status,
+ });
+
+ return await response.json();
+ } catch (error) {
+ trackEvent(AnalyticsEvents.API_ERROR, {
+ endpoint: endpoint,
+ error_message: error.message,
+ error_type: error.name,
+ });
+
+ throw error;
+ }
+ };
+
+ return { fetchData };
+}
+```
+
+---
+
+## Performance Tracking
+
+### Page Load Performance
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function PerformanceTracker() {
+ const { trackEvent } = useAnalytics();
+
+ useEffect(() => {
+ // Track page load performance
+ if ('performance' in window) {
+ const perfData = window.performance.timing;
+ const pageLoadTime = perfData.loadEventEnd - perfData.navigationStart;
+
+ trackEvent(AnalyticsEvents.PERFORMANCE, {
+ metric: 'page_load_time',
+ value: pageLoadTime,
+ page: window.location.pathname,
+ });
+ }
+ }, []);
+
+ return null;
+}
+```
+
+### Custom Performance Metrics
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ComponentWithPerformance() {
+ const { trackEvent } = useAnalytics();
+ const [loadTime, setLoadTime] = useState(0);
+
+ useEffect(() => {
+ const startTime = performance.now();
+
+ // Simulate some async work
+ setTimeout(() => {
+ const endTime = performance.now();
+ const duration = endTime - startTime;
+
+ setLoadTime(duration);
+
+ trackEvent(AnalyticsEvents.PERFORMANCE, {
+ metric: 'component_load_time',
+ value: duration,
+ component_name: 'ComponentWithPerformance',
+ });
+ }, 1000);
+ }, []);
+
+ return Loaded in {loadTime}ms
;
+}
+```
+
+---
+
+## Custom Navigation
+
+### SPA Navigation Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function SpaNavigation() {
+ const { trackPageview } = useAnalytics();
+
+ const navigateTo = (path: string) => {
+ // Track the navigation
+ trackPageview(path);
+
+ // Perform navigation
+ window.history.pushState({}, '', path);
+ // Or use your router: router.push(path);
+ };
+
+ return (
+
+ );
+}
+```
+
+### Modal Navigation
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ModalWithTracking({ modalId, children }) {
+ const { trackEvent, trackPageview } = useAnalytics();
+
+ const openModal = () => {
+ trackEvent(AnalyticsEvents.MODAL_OPEN, {
+ modal_id: modalId,
+ });
+
+ // Track modal as a "page" view
+ trackPageview(`/modal/${modalId}`);
+ };
+
+ const closeModal = () => {
+ trackEvent(AnalyticsEvents.MODAL_CLOSE, {
+ modal_id: modalId,
+ });
+
+ // Track return to previous page
+ trackPageview(window.location.pathname);
+ };
+
+ return (
+
+
+
+ {children}
+
+
+
+
{cable.name}
+
+
+
+
+ );
+}
+```
+
+### Wind Farm Construction Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function WindFarmProjectPage({ project }) {
+ const { trackEvent } = useAnalytics();
+
+ const handleProjectInquiry = () => {
+ trackEvent('project_inquiry', {
+ project_type: 'wind_farm',
+ project_location: project.location,
+ project_size: project.size,
+ project_stage: project.stage,
+ cable_requirements: project.cableRequirements,
+ });
+ };
+
+ const handleCableCalculation = () => {
+ trackEvent('cable_calculation', {
+ calculation_type: 'voltage_drop',
+ cable_type: project.cableType,
+ cable_length: project.cableLength,
+ load_current: project.loadCurrent,
+ result: project.calculationResult,
+ });
+ };
+
+ return (
+
+
{project.name}
+
+
+
+ );
+}
+```
+
+---
+
+## Testing Analytics
+
+### Mock Analytics for Tests
+
+```tsx
+// __tests__/analytics-mock.ts
+export const mockAnalytics = {
+ track: jest.fn(),
+ trackPageview: jest.fn(),
+};
+
+jest.mock('@/lib/services/create-services', () => ({
+ getAppServices: () => ({
+ analytics: mockAnalytics,
+ }),
+}));
+
+// Usage in tests
+import { render, screen, fireEvent } from '@testing-library/react';
+import { mockAnalytics } from './analytics-mock';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+test('tracks button click', () => {
+ const TestComponent = () => {
+ const { trackEvent } = useAnalytics();
+ return ;
+ };
+
+ render();
+ fireEvent.click(screen.getByText('Click'));
+
+ expect(mockAnalytics.track).toHaveBeenCalledWith('test_event');
+});
+```
+
+### Development Mode Testing
+
+```tsx
+// In development mode, check console logs:
+// [Umami] Tracked event: product_add_to_cart { product_id: '123' }
+// [Umami] Tracked pageview: /products/123
+
+// To test without sending data to Umami:
+// 1. Remove NEXT_PUBLIC_UMAMI_WEBSITE_ID from .env
+// 2. Or set it to an empty string
+// 3. Check console logs to verify events are being tracked
+```
+
+---
+
+## Performance Tips
+
+### 1. Debounce High-Frequency Events
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { debounce } from 'lodash';
+
+function SearchInput() {
+ const { trackEvent } = useAnalytics();
+
+ const debouncedTrack = debounce((query: string) => {
+ trackEvent('search', { search_query: query });
+ }, 500);
+
+ const handleChange = (e: React.ChangeEvent) => {
+ debouncedTrack(e.target.value);
+ };
+
+ return ;
+}
+```
+
+### 2. Batch Events (if needed)
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function BatchTracker() {
+ const { trackEvent } = useAnalytics();
+ const eventQueue = useRef>([]);
+
+ const addToQueue = (name: string, props: any) => {
+ eventQueue.current.push({ name, props });
+ };
+
+ const flushQueue = () => {
+ eventQueue.current.forEach(({ name, props }) => {
+ trackEvent(name, props);
+ });
+ eventQueue.current = [];
+ };
+
+ // Flush queue on page unload
+ useEffect(() => {
+ const handleBeforeUnload = () => flushQueue();
+ window.addEventListener('beforeunload', handleBeforeUnload);
+ return () => window.removeEventListener('beforeunload', handleBeforeUnload);
+ }, []);
+
+ return null;
+}
+```
+
+### 3. Use Web Vitals for Performance
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function WebVitalsTracker() {
+ const { trackEvent } = useAnalytics();
+
+ useEffect(() => {
+ // Track Core Web Vitals
+ if ('PerformanceObserver' in window) {
+ const observer = new PerformanceObserver((list) => {
+ for (const entry of list.getEntries()) {
+ if (entry.entryType === 'largest-contentful-paint') {
+ trackEvent(AnalyticsEvents.PERFORMANCE, {
+ metric: 'lcp',
+ value: entry.startTime,
+ });
+ }
+ if (entry.entryType === 'first-input-delay') {
+ trackEvent(AnalyticsEvents.PERFORMANCE, {
+ metric: 'fid',
+ value: entry.processingStart - entry.startTime,
+ });
+ }
+ if (entry.entryType === 'layout-shift') {
+ trackEvent(AnalyticsEvents.PERFORMANCE, {
+ metric: 'cls',
+ value: entry.value,
+ });
+ }
+ }
+ });
+
+ observer.observe({ entryTypes: ['largest-contentful-paint', 'first-input-delay', 'layout-shift'] });
+ }
+ }, []);
+
+ return null;
+}
+```
+
+---
+
+## Summary
+
+This examples file demonstrates how to implement comprehensive analytics tracking for various scenarios:
+
+- โ
**Basic interactions** (buttons, links, forms)
+- โ
**E-commerce** (product views, cart, purchases)
+- โ
**User authentication** (login, signup, logout)
+- โ
**Search & filtering** (search queries, filter applications)
+- โ
**Content tracking** (blog posts, videos, downloads)
+- โ
**Error tracking** (error boundaries, API errors)
+- โ
**Performance tracking** (page loads, custom metrics)
+- โ
**Custom navigation** (SPA, modals)
+- โ
**Business-specific events** (KLZ Cables, wind farms)
+
+Remember to:
+1. Use the `useAnalytics` hook for client-side tracking
+2. Import events from `AnalyticsEvents` for consistency
+3. Include relevant context in your events
+4. Respect privacy regulations (GDPR, etc.)
+5. Test in development mode before deploying
diff --git a/components/analytics/QUICK_REFERENCE.md b/components/analytics/QUICK_REFERENCE.md
new file mode 100644
index 00000000..80f52bbd
--- /dev/null
+++ b/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 ;
+}
+```
+
+### Track a Pageview
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function MyComponent() {
+ const { trackPageview } = useAnalytics();
+
+ const navigate = () => {
+ trackPageview('/custom-path');
+ // Navigate...
+ };
+
+ return ;
+}
+```
+
+### 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 ;
+}
+```
+
+## 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
diff --git a/components/analytics/README.md b/components/analytics/README.md
new file mode 100644
index 00000000..63ef6485
--- /dev/null
+++ b/components/analytics/README.md
@@ -0,0 +1,443 @@
+# Umami Analytics Integration
+
+This project uses [Umami Analytics](https://umami.is/) for privacy-focused website analytics. The implementation is modern, clean, and follows Next.js best practices.
+
+## Overview
+
+The analytics system consists of:
+
+1. **`UmamiScript`** - Loads the Umami tracking script
+2. **`AnalyticsProvider`** - Tracks pageviews on route changes
+3. **`useAnalytics`** - Custom hook for tracking custom events
+4. **`analytics-events.ts`** - Centralized event definitions
+5. **`UmamiAnalyticsService`** - Service layer for analytics operations
+
+## Setup
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```bash
+# Required: Your Umami website ID
+NEXT_PUBLIC_UMAMI_WEBSITE_ID=59a7db94-0100-4c7e-98ef-99f45b17f9c3
+
+# Optional: Custom Umami script URL (defaults to https://analytics.infra.mintel.me/script.js)
+NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://analytics.infra.mintel.me/script.js
+```
+
+### Docker Compose
+
+The `docker-compose.yml` already includes the environment variables:
+
+```yaml
+environment:
+ - NEXT_PUBLIC_UMAMI_WEBSITE_ID=${NEXT_PUBLIC_UMAMI_WEBSITE_ID}
+ - NEXT_PUBLIC_UMAMI_SCRIPT_URL=${NEXT_PUBLIC_UMAMI_SCRIPT_URL:-https://analytics.infra.mintel.me/script.js}
+```
+
+## Usage
+
+### 1. Automatic Pageview Tracking
+
+The `AnalyticsProvider` component automatically tracks pageviews on client-side route changes. It's already included in your layout:
+
+```tsx
+// app/[locale]/layout.tsx
+
+
+
+ {children}
+
+
+
+```
+
+### 2. Tracking Custom Events
+
+Use the `useAnalytics` hook to track custom events:
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ProductCard({ product }) {
+ const { trackEvent } = useAnalytics();
+
+ const handleAddToCart = () => {
+ trackEvent(AnalyticsEvents.PRODUCT_ADD_TO_CART, {
+ product_id: product.id,
+ product_name: product.name,
+ product_category: product.category,
+ price: product.price,
+ });
+ };
+
+ return (
+
+ );
+}
+```
+
+### 3. Tracking Pageviews Manually
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+
+function CustomNavigation() {
+ const { trackPageview } = useAnalytics();
+
+ const navigateToCustomPage = () => {
+ // Track a custom pageview
+ trackPageview('/custom-path?param=value');
+
+ // Then perform navigation
+ window.location.href = '/custom-path?param=value';
+ };
+
+ return ;
+}
+```
+
+### 4. Using Predefined Events
+
+The `analytics-events.ts` file provides a centralized list of events:
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents, AnalyticsEventProperties } from '@/components/analytics/analytics-events';
+
+function ContactForm() {
+ const { trackEvent } = useAnalytics();
+
+ const handleSubmit = (formData: FormData) => {
+ // Track form submission
+ trackEvent(AnalyticsEvents.CONTACT_FORM_SUBMIT, {
+ form_id: 'contact-form',
+ form_name: 'Contact Us',
+ form_fields: {
+ name: formData.get('name'),
+ email: formData.get('email'),
+ message: formData.get('message'),
+ },
+ });
+ };
+
+ return ;
+}
+```
+
+### 5. E-commerce Tracking Example
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ProductPage({ product }) {
+ const { trackEvent } = useAnalytics();
+
+ // Track product view on page load
+ useEffect(() => {
+ trackEvent(AnalyticsEvents.PRODUCT_VIEW, {
+ product_id: product.id,
+ product_name: product.name,
+ product_category: product.category,
+ price: product.price,
+ });
+ }, [product]);
+
+ const handleAddToCart = () => {
+ trackEvent(AnalyticsEvents.PRODUCT_ADD_TO_CART, {
+ product_id: product.id,
+ product_name: product.name,
+ product_category: product.category,
+ price: product.price,
+ quantity: 1,
+ });
+ };
+
+ const handlePurchase = () => {
+ trackEvent(AnalyticsEvents.PRODUCT_PURCHASE, {
+ product_id: product.id,
+ product_name: product.name,
+ product_category: product.category,
+ price: product.price,
+ transaction_id: 'TXN-12345',
+ currency: 'EUR',
+ });
+ };
+
+ return (
+
+
{product.name}
+
{product.description}
+
+
+
+ handleSearch(e.target.value)} />
+
+
+ );
+}
+```
+
+### 7. User Account Events
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function LoginForm() {
+ const { trackEvent } = useAnalytics();
+
+ const handleLogin = (email: string) => {
+ trackEvent(AnalyticsEvents.USER_LOGIN, {
+ user_email: email,
+ login_method: 'email',
+ });
+ };
+
+ const handleLogout = () => {
+ trackEvent(AnalyticsEvents.USER_LOGOUT, {
+ user_id: 'user-123',
+ });
+ };
+
+ return (
+
+
+
+
+ );
+}
+```
+
+### 8. Error Tracking
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+
+function ErrorBoundary({ children }) {
+ const { trackEvent } = useAnalytics();
+
+ const handleError = (error: Error, errorInfo: React.ErrorInfo) => {
+ trackEvent(AnalyticsEvents.ERROR, {
+ error_message: error.message,
+ error_stack: error.stack,
+ error_component: errorInfo.componentStack,
+ });
+ };
+
+ return (
+
+ {children}
+
+ );
+}
+```
+
+## Event Reference
+
+### Common Events
+
+| Event Name | Description | Example Properties |
+|------------|-------------|-------------------|
+| `pageview` | Page view | `{ url: '/products/123' }` |
+| `button_click` | Button clicked | `{ button_id: 'cta-primary', page: 'homepage' }` |
+| `link_click` | Link clicked | `{ link_url: '/products', link_text: 'View Products' }` |
+| `form_submit` | Form submitted | `{ form_id: 'contact-form', form_name: 'Contact Us' }` |
+| `product_view` | Product page viewed | `{ product_id: '123', product_name: 'Cable', price: 99.99 }` |
+| `product_add_to_cart` | Product added to cart | `{ product_id: '123', quantity: 1 }` |
+| `product_purchase` | Product purchased | `{ product_id: '123', transaction_id: 'TXN-123' }` |
+| `search` | Search performed | `{ search_query: 'cable', search_results_count: 42 }` |
+| `filter_apply` | Filter applied | `{ filter_type: 'category', filter_value: 'high-voltage' }` |
+| `user_login` | User logged in | `{ user_email: 'user@example.com' }` |
+| `user_signup` | User signed up | `{ user_email: 'user@example.com' }` |
+| `error` | Error occurred | `{ error_message: 'Something went wrong' }` |
+
+### Custom Events
+
+You can create any custom event by passing a string name:
+
+```tsx
+trackEvent('custom_event_name', {
+ custom_property: 'value',
+ another_property: 123,
+});
+```
+
+## Best Practices
+
+### 1. Use Centralized Event Definitions
+
+Always use the `AnalyticsEvents` constant for consistency:
+
+```tsx
+// โ
Good
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
+trackEvent(AnalyticsEvents.PRODUCT_ADD_TO_CART, { ... });
+
+// โ Avoid
+trackEvent('product_add_to_cart', { ... }); // Typo risk!
+```
+
+### 2. Include Relevant Context
+
+Add context to your events to make them more useful:
+
+```tsx
+// โ
Good
+trackEvent(AnalyticsEvents.BUTTON_CLICK, {
+ button_id: 'cta-primary',
+ page: 'homepage',
+ section: 'hero',
+ user_type: 'guest',
+});
+
+// โ Less useful
+trackEvent(AnalyticsEvents.BUTTON_CLICK, {
+ button_id: 'cta-primary',
+});
+```
+
+### 3. Track Meaningful Events
+
+Focus on business-critical events:
+
+- โ
Product views, add to cart, purchases
+- โ
Form submissions (contact, newsletter, quote requests)
+- โ
Search queries and filter usage
+- โ
User authentication events
+- โ
Error occurrences
+
+- โ Every mouse move
+- โ Every scroll event (unless specifically needed)
+- โ Every hover state change
+
+### 4. Respect Privacy
+
+- Don't track personally identifiable information (PII)
+- Don't track sensitive data (passwords, credit cards, etc.)
+- Use anonymized IDs where possible
+- Follow GDPR and other privacy regulations
+
+### 5. Test in Development
+
+The analytics system includes development mode logging:
+
+```bash
+# In development, you'll see console logs:
+[Umami] Tracked event: product_add_to_cart { product_id: '123' }
+[Umami] Tracked pageview: /products/123
+```
+
+## Troubleshooting
+
+### Analytics Not Working
+
+1. **Check environment variables:**
+ ```bash
+ echo $NEXT_PUBLIC_UMAMI_WEBSITE_ID
+ ```
+
+2. **Verify the script is loading:**
+ - Open browser DevTools
+ - Check Network tab for `script.js` request
+ - Check Console for any errors
+
+3. **Check Umami dashboard:**
+ - Log into your Umami instance
+ - Verify the website ID matches
+ - Check if data is being received
+
+### Development Mode
+
+In development mode, you'll see console logs for all tracked events. This helps you verify that events are being tracked correctly without affecting your production analytics.
+
+### Disabling Analytics
+
+To disable analytics (e.g., for local development), simply remove the `NEXT_PUBLIC_UMAMI_WEBSITE_ID` environment variable:
+
+```bash
+# .env.local (not committed to git)
+# NEXT_PUBLIC_UMAMI_WEBSITE_ID=
+```
+
+## Performance
+
+The analytics implementation is optimized for performance:
+
+- โ
Uses Next.js `Script` component with `afterInteractive` strategy
+- โ
Script loads after page is interactive
+- โ
No blocking of critical rendering path
+- โ
Minimal JavaScript bundle size
+- โ
Automatic cleanup on route changes
+
+## Security
+
+- โ
Environment variables are not exposed to the client (except `NEXT_PUBLIC_` prefixed ones)
+- โ
Script URL can be customized for self-hosted Umami instances
+- โ
Error handling prevents analytics from breaking your app
+- โ
Type-safe event tracking with TypeScript
+
+## Additional Resources
+
+- [Umami Documentation](https://umami.is/docs)
+- [Next.js Script Component](https://nextjs.org/docs/app/api-reference/components/script)
+- [Analytics Best Practices](https://umami.is/docs/best-practices)
+
+## Support
+
+For issues or questions about the analytics implementation, check:
+1. This README for usage examples
+2. The component source code for implementation details
+3. The Umami documentation for platform-specific questions
diff --git a/components/analytics/SUMMARY.md b/components/analytics/SUMMARY.md
new file mode 100644
index 00000000..f206ef08
--- /dev/null
+++ b/components/analytics/SUMMARY.md
@@ -0,0 +1,268 @@
+# Umami Analytics Implementation Summary
+
+## โ
Implementation Status: COMPLETE
+
+Your project now has a **modern, clean, and comprehensive** Umami analytics implementation.
+
+## What Was Already Implemented
+
+The project already had a solid foundation:
+
+1. **`UmamiScript.tsx`** - Next.js Script component for loading analytics
+2. **`AnalyticsProvider.tsx`** - Automatic pageview tracking on route changes
+3. **`UmamiAnalyticsService.ts`** - Service layer for event tracking
+4. **Environment variables** in `docker-compose.yml`
+
+## What Was Enhanced
+
+### 1. **Enhanced UmamiScript** (`components/analytics/UmamiScript.tsx`)
+- โ
Added TypeScript props interface for customization
+- โ
Added JSDoc documentation with usage examples
+- โ
Added error handling for script loading failures
+- โ
Added development mode warnings
+- โ
Improved type safety and comments
+
+### 2. **Enhanced AnalyticsProvider** (`components/analytics/AnalyticsProvider.tsx`)
+- โ
Added comprehensive JSDoc documentation
+- โ
Added development mode logging
+- โ
Improved code comments
+
+### 3. **New Custom Hook** (`components/analytics/useAnalytics.ts`)
+- โ
Type-safe `useAnalytics` hook for easy event tracking
+- โ
`trackEvent()` method for custom events
+- โ
`trackPageview()` method for manual pageview tracking
+- โ
`useCallback` optimization for performance
+- โ
Development mode logging
+
+### 4. **Event Definitions** (`components/analytics/analytics-events.ts`)
+- โ
Centralized event constants for consistency
+- โ
Type-safe event names
+- โ
Helper functions for common event properties
+- โ
30+ predefined events for various use cases
+
+### 5. **Comprehensive Documentation**
+- โ
**README.md** - Full documentation with setup, usage, and best practices
+- โ
**EXAMPLES.md** - 20+ practical examples for different scenarios
+- โ
**QUICK_REFERENCE.md** - Quick start guide and troubleshooting
+- โ
**SUMMARY.md** - This file
+
+## File Structure
+
+```
+components/analytics/
+โโโ UmamiScript.tsx # Script loader component
+โโโ AnalyticsProvider.tsx # Route change tracker
+โโโ useAnalytics.ts # Custom hook for event tracking
+โโโ analytics-events.ts # Event definitions and helpers
+โโโ README.md # Full documentation
+โโโ EXAMPLES.md # Practical examples
+โโโ QUICK_REFERENCE.md # Quick start guide
+โโโ SUMMARY.md # This summary
+```
+
+## Key Features
+
+### ๐ Modern Implementation
+- Uses Next.js `Script` component (not old-school `