unchained/manoon-headless
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: Implement comprehensive OpenPanel analytics tracking

Browse Source 
Complete analytics overhaul with 30+ tracking events:

E-commerce Events:
- Product views, image views, variant selection
- Add/remove from cart, quantity changes
- Cart open and abandonment tracking
- Checkout funnel (all steps)
- Payment/shipping method selection
- Order completion with revenue tracking

User Engagement:
- Search queries with filters
- CTA clicks, external link clicks
- Element engagement (click/hover/view)
- Newsletter signups
- Promo code usage
- Wishlist actions

User Identity:
- User identification
- Property setting
- Screen/session tracking

Technical:
- Proper TypeScript types for all events
- Increment/decrement counters
- Pending revenue for cart abandonment
- Comprehensive error handling

Includes complete documentation in docs/ANALYTICS_GUIDE.md
This commit is contained in:
Unchained
2026-03-29 20:25:21 +02:00
parent 038a574c6e
commit 3c3f4129c8
3 changed files with 790 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
docs/ANALYTICS_GUIDE.md Normal file
View File

@@ -0,0 +1,388 @@
# 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