manoon-headless/docs/ANALYTICS_GUIDE.md

Comprehensive OpenPanel Analytics Guide

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

Quick Start

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

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

trackProductImageView("prod_123", 2); // Viewed 3rd image

trackVariantSelect - Track variant/option selection

trackVariantSelect("prod_123", "50ml", 2890);

2. Cart Events

trackAddToCart - Track adding items to cart

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

trackRemoveFromCart({
  id: "prod_123",
  name: "Manoon Anti-Age Serum",
  price: 2890,
  quantity: 1,
  variant: "50ml",
});

trackQuantityChange - Track quantity adjustments

trackQuantityChange(
  cartItem,
  1, // old quantity
  3  // new quantity
);

trackCartOpen - Track cart drawer/modal open

trackCartOpen({
  total: 5780,
  currency: "RSD",
  item_count: 2,
  items: [/* cart items */],
  coupon_code: "SAVE10",
});

trackCartAbandonment - Track cart abandonment

trackCartAbandonment(
  cartData,
  45000 // time spent in cart (ms)
);

3. Checkout Events

trackCheckoutStarted - Track checkout initiation

trackCheckoutStarted({
  total: 5780,
  currency: "RSD",
  item_count: 2,
  items: [/* cart items */],
  coupon_code: "SAVE10",
});

trackCheckoutStep - Track checkout step progression

// 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

trackPaymentMethodSelect("cod", 5780);

trackShippingMethodSelect - Track shipping method selection

trackShippingMethodSelect("Standard", 480);

4. Order Events

trackOrderCompleted - Track successful order with revenue

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

trackSearch({
  query: "anti aging serum",
  results_count: 12,
  filters: { category: "serums", price_range: "2000-3000" },
  category: "serums",
});

2. General Engagement

trackEngagement - Track element interactions

// 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

trackCTAClick(
  "Shop Now",           // CTA name
  "hero_section",       // Location
  "/products"           // Destination (optional)
);

4. External Links

trackExternalLink - Track outbound links

trackExternalLink(
  "https://instagram.com/manoonoils",
  "Instagram",
  "footer"
);

5. Newsletter

trackNewsletterSignup - Track email subscriptions

trackNewsletterSignup(
  "customer@example.com",
  "footer" // Location of signup form
);

6. Promo Codes

trackPromoCode - Track coupon/promo code usage

trackPromoCode(
  "SAVE10",
  578,    // discount amount
  true    // success
);

7. Wishlist

trackWishlistAction - Track wishlist interactions

// 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:

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:

setUserProperties({
  loyalty_tier: "gold",
  last_purchase_date: "2024-03-25",
  preferred_category: "serums",
});

---

Session/Screen Tracking

trackScreenView

Track page views manually:

trackScreenView(
  "/products/anti-age-serum",
  "Manoon Anti-Age Serum - ManoonOils"
);

trackSessionStart

Track new sessions:

useEffect(() => {
  trackSessionStart();
}, []);

---

Best Practices

1. Always Wrap in try-catch

Tracking should never break the user experience:

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:

// 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