manoon-headless/docs/ANALYTICS_GUIDE.md

# Comprehensive OpenPanel Analytics Guide

This guide documents all tracking events implemented in the ManoonOils storefront.

## Quick Start

```typescript
import { useAnalytics } from "@/lib/analytics";

function MyComponent() {
  const { trackProductView, trackAddToCart, trackOrderCompleted } = useAnalytics();
  
  // Use tracking functions...
}
```

---

## E-Commerce Events

### 1. Product Views

**trackProductView** - Track when user views a product
```typescript
trackProductView({
  id: "prod_123",
  name: "Manoon Anti-Age Serum",
  price: 2890,
  currency: "RSD",
  category: "Serums",
  sku: "MAN-001",
  in_stock: true,
});
```

**trackProductImageView** - Track product image gallery interactions
```typescript
trackProductImageView("prod_123", 2); // Viewed 3rd image
```

**trackVariantSelect** - Track variant/option selection
```typescript
trackVariantSelect("prod_123", "50ml", 2890);
```

### 2. Cart Events

**trackAddToCart** - Track adding items to cart
```typescript
trackAddToCart({
  id: "prod_123",
  name: "Manoon Anti-Age Serum",
  price: 2890,
  currency: "RSD",
  quantity: 2,
  variant: "50ml",
  sku: "MAN-001-50",
});
```

**trackRemoveFromCart** - Track removing items from cart
```typescript
trackRemoveFromCart({
  id: "prod_123",
  name: "Manoon Anti-Age Serum",
  price: 2890,
  quantity: 1,
  variant: "50ml",
});
```

**trackQuantityChange** - Track quantity adjustments
```typescript
trackQuantityChange(
  cartItem,
  1, // old quantity
  3  // new quantity
);
```

**trackCartOpen** - Track cart drawer/modal open
```typescript
trackCartOpen({
  total: 5780,
  currency: "RSD",
  item_count: 2,
  items: [/* cart items */],
  coupon_code: "SAVE10",
});
```

**trackCartAbandonment** - Track cart abandonment
```typescript
trackCartAbandonment(
  cartData,
  45000 // time spent in cart (ms)
);
```

### 3. Checkout Events

**trackCheckoutStarted** - Track checkout initiation
```typescript
trackCheckoutStarted({
  total: 5780,
  currency: "RSD",
  item_count: 2,
  items: [/* cart items */],
  coupon_code: "SAVE10",
});
```

**trackCheckoutStep** - Track checkout step progression
```typescript
// Step progression
trackCheckoutStep({
  step: "email",
  value: 5780,
  currency: "RSD",
});

// With error
trackCheckoutStep({
  step: "shipping",
  error: "Invalid postal code",
});

// Final step
trackCheckoutStep({
  step: "complete",
  payment_method: "cod",
  shipping_method: "Standard",
});
```

**trackPaymentMethodSelect** - Track payment method selection
```typescript
trackPaymentMethodSelect("cod", 5780);
```

**trackShippingMethodSelect** - Track shipping method selection
```typescript
trackShippingMethodSelect("Standard", 480);
```

### 4. Order Events

**trackOrderCompleted** - Track successful order with revenue
```typescript
trackOrderCompleted({
  order_id: "order_uuid",
  order_number: "1599",
  total: 6260,
  currency: "RSD",
  item_count: 2,
  shipping_cost: 480,
  customer_email: "customer@example.com",
  payment_method: "cod",
  coupon_code: "SAVE10",
});
```

---

## User Engagement Events

### 1. Search

**trackSearch** - Track search queries
```typescript
trackSearch({
  query: "anti aging serum",
  results_count: 12,
  filters: { category: "serums", price_range: "2000-3000" },
  category: "serums",
});
```

### 2. General Engagement

**trackEngagement** - Track element interactions
```typescript
// Element click
trackEngagement({
  element: "hero_cta",
  action: "click",
  value: "Shop Now",
});

// Element hover
trackEngagement({
  element: "product_card",
  action: "hover",
  value: "prod_123",
});

// Element view (scroll into view)
trackEngagement({
  element: "testimonials_section",
  action: "view",
  metadata: { section_position: "below_fold" },
});
```

### 3. CTA Tracking

**trackCTAClick** - Track call-to-action buttons
```typescript
trackCTAClick(
  "Shop Now",           // CTA name
  "hero_section",       // Location
  "/products"           // Destination (optional)
);
```

### 4. External Links

**trackExternalLink** - Track outbound links
```typescript
trackExternalLink(
  "https://instagram.com/manoonoils",
  "Instagram",
  "footer"
);
```

### 5. Newsletter

**trackNewsletterSignup** - Track email subscriptions
```typescript
trackNewsletterSignup(
  "customer@example.com",
  "footer" // Location of signup form
);
```

### 6. Promo Codes

**trackPromoCode** - Track coupon/promo code usage
```typescript
trackPromoCode(
  "SAVE10",
  578,    // discount amount
  true    // success
);
```

### 7. Wishlist

**trackWishlistAction** - Track wishlist interactions
```typescript
// Add to wishlist
trackWishlistAction("add", "prod_123", "Anti-Age Serum");

// Remove from wishlist
trackWishlistAction("remove", "prod_123", "Anti-Age Serum");
```

---

## User Identification

### identifyUser

Identify users across sessions:
```typescript
identifyUser({
  profileId: "user_uuid",
  email: "customer@example.com",
  firstName: "John",
  lastName: "Doe",
  phone: "+38161123456",
  properties: {
    signup_date: "2024-03-01",
    preferred_language: "sr",
    total_orders: 5,
  },
});
```

### setUserProperties

Set global user properties:
```typescript
setUserProperties({
  loyalty_tier: "gold",
  last_purchase_date: "2024-03-25",
  preferred_category: "serums",
});
```

---

## Session/Screen Tracking

### trackScreenView

Track page views manually:
```typescript
trackScreenView(
  "/products/anti-age-serum",
  "Manoon Anti-Age Serum - ManoonOils"
);
```

### trackSessionStart

Track new sessions:
```typescript
useEffect(() => {
  trackSessionStart();
}, []);
```

---

## Best Practices

### 1. Always Wrap in try-catch
Tracking should never break the user experience:
```typescript
try {
  trackAddToCart(product);
} catch (e) {
  console.error("Tracking failed:", e);
}
```

### 2. Use Consistent Naming
- Use snake_case for property names
- Be consistent with event names
- Use past tense for events (e.g., `product_viewed` not `view_product`)

### 3. Include Context
Always include relevant context:
```typescript
// Good
trackCTAClick("Shop Now", "hero_section", "/products");

// Less useful
trackCTAClick("button_click");
```

### 4. Track Revenue Properly
Always use `trackOrderCompleted` for final purchases - it includes both event tracking and revenue tracking.

### 5. Increment/Decrement Counters
Use increment/decrement for user-level metrics:
- Total orders: `op.increment({ total_orders: 1 })`
- Wishlist items: `op.increment({ wishlist_items: 1 })`
- Product views: `op.increment({ product_views: 1 })`

---

## Analytics Dashboard Views

With this implementation, you can create OpenPanel dashboards for:

1. **E-commerce Funnel**
   - Product views → Add to cart → Checkout started → Order completed
   - Conversion rates at each step
   - Cart abandonment rate

2. **Revenue Analytics**
   - Total revenue by period
   - Revenue by payment method
   - Revenue by product category
   - Average order value

3. **User Behavior**
   - Most viewed products
   - Popular search terms
   - CTA click rates
   - Time to purchase

4. **User Properties**
   - User segments by total orders
   - Repeat customers
   - Newsletter subscribers
   - Wishlist users

---

## Debugging

Check browser console for tracking logs. All tracking functions log to console in development mode.

OpenPanel dashboard: https://op.nodecrew.me