diff --git a/CUSTOMER_SPA_MASTER_PLAN.md b/CUSTOMER_SPA_MASTER_PLAN.md index 9efb4da..578a037 100644 --- a/CUSTOMER_SPA_MASTER_PLAN.md +++ b/CUSTOMER_SPA_MASTER_PLAN.md @@ -24,12 +24,14 @@ This document outlines the comprehensive strategy for building WooNooW's custome 1. [Architecture Overview](#architecture-overview) 2. [Deployment Modes](#deployment-modes) -3. [Feature Scope](#feature-scope) -4. [UX Best Practices](#ux-best-practices) -5. [Technical Stack](#technical-stack) -6. [Implementation Roadmap](#implementation-roadmap) -7. [API Requirements](#api-requirements) -8. [Performance Targets](#performance-targets) +3. [SEO Strategy](#seo-strategy) +4. [Tracking & Analytics](#tracking--analytics) +5. [Feature Scope](#feature-scope) +6. [UX Best Practices](#ux-best-practices) +7. [Technical Stack](#technical-stack) +8. [Implementation Roadmap](#implementation-roadmap) +9. [API Requirements](#api-requirements) +10. [Performance Targets](#performance-targets) --- @@ -39,35 +41,53 @@ This document outlines the comprehensive strategy for building WooNooW's custome ``` woonoow/ -├── admin-spa/ # Admin interface (existing) -├── customer-spa/ # Customer frontend (NEW) +├── admin-spa/ # Admin interface ONLY │ ├── src/ -│ │ ├── pages/ +│ │ ├── routes/ # Admin pages (Dashboard, Products, Orders) +│ │ └── components/ # Admin components +│ └── public/ +│ +├── customer-spa/ # Customer frontend ONLY (Storefront + My Account) +│ ├── src/ +│ │ ├── pages/ # Customer pages │ │ │ ├── Shop/ # Product listing │ │ │ ├── Product/ # Product detail │ │ │ ├── Cart/ # Shopping cart │ │ │ ├── Checkout/ # Checkout process -│ │ │ ├── Account/ # My Account dashboard -│ │ │ └── Orders/ # Order history +│ │ │ └── Account/ # My Account (orders, profile, addresses) │ │ ├── components/ │ │ │ ├── ProductCard/ │ │ │ ├── CartDrawer/ │ │ │ ├── CheckoutForm/ │ │ │ └── AddressForm/ │ │ └── lib/ -│ │ ├── api/ +│ │ ├── api/ # API client │ │ ├── cart/ # Cart state management -│ │ └── checkout/ # Checkout logic +│ │ ├── checkout/ # Checkout logic +│ │ └── tracking/ # Analytics & pixel tracking │ └── public/ -├── includes/ -│ ├── Admin/ -│ └── Frontend/ -│ ├── Shortcodes/ # [woonoow_cart], [woonoow_checkout] -│ ├── SPA/ # Full SPA mode handler -│ └── Api/ # Customer API endpoints -└── woonoow.php +│ +└── includes/ + ├── Admin/ # Admin backend (serves admin-spa) + │ ├── AdminController.php + │ └── MenuManager.php + │ + └── Frontend/ # Customer backend (serves customer-spa) + ├── ShortcodeManager.php # [woonoow_cart], [woonoow_checkout] + ├── SpaManager.php # Full SPA mode handler + └── Api/ # Customer API endpoints + ├── ShopController.php + ├── CartController.php + └── CheckoutController.php ``` +**Key Points:** +- ✅ **admin-spa/** - Admin interface only +- ✅ **customer-spa/** - Storefront + My Account in one app +- ✅ **includes/Admin/** - Admin backend logic +- ✅ **includes/Frontend/** - Customer backend logic +- ✅ Clear separation of concerns + --- ## Deployment Modes @@ -141,6 +161,249 @@ woonoow/ --- +## SEO Strategy + +### Hybrid Rendering for SEO Compatibility + +**Problem:** Full SPA can hurt SEO because search engines see empty HTML. + +**Solution:** Hybrid rendering - SSR for SEO-critical pages, CSR for interactive pages. + +### Rendering Strategy + +``` +┌─────────────────────┬──────────────┬─────────────────┐ +│ Page Type │ Rendering │ SEO Needed? │ +├─────────────────────┼──────────────┼─────────────────┤ +│ Product Listing │ SSR │ ✅ Yes │ +│ Product Detail │ SSR │ ✅ Yes │ +│ Category Pages │ SSR │ ✅ Yes │ +│ Search Results │ SSR │ ✅ Yes │ +│ Cart │ CSR (SPA) │ ❌ No │ +│ Checkout │ CSR (SPA) │ ❌ No │ +│ My Account │ CSR (SPA) │ ❌ No │ +│ Order Confirmation │ CSR (SPA) │ ❌ No │ +└─────────────────────┴──────────────┴─────────────────┘ +``` + +### How SSR Works + +**Product Page Example:** +```php + + + +
+

get_name(); ?>

+
get_price_html(); ?>
+
get_description(); ?>
+ + + +
+ + +``` + +**Benefits:** +- ✅ **Yoast SEO** works - sees full HTML +- ✅ **RankMath** works - sees full HTML +- ✅ **Google** crawls full content +- ✅ **Social sharing** shows correct meta tags +- ✅ **React adds interactivity** after page load + +### SEO Plugin Compatibility + +**Supported SEO Plugins:** +- ✅ Yoast SEO +- ✅ RankMath +- ✅ All in One SEO +- ✅ SEOPress +- ✅ The SEO Framework + +**How it works:** +1. WordPress renders product page with full HTML +2. SEO plugin injects meta tags, schema markup +3. React hydrates for interactivity +4. Search engines see complete, SEO-optimized HTML + +--- + +## Tracking & Analytics + +### Full Compatibility with Tracking Plugins + +**Goal:** Ensure all tracking plugins work seamlessly with customer-spa. + +### Strategy: Trigger WooCommerce Events + +**Key Insight:** Keep WooCommerce classes and trigger WooCommerce events so tracking plugins can listen. + +### Supported Tracking Plugins + +✅ **PixelMySite** - Facebook, TikTok, Pinterest pixels +✅ **Google Analytics** - GA4, Universal Analytics +✅ **Google Tag Manager** - Full dataLayer support +✅ **Facebook Pixel** - Standard events +✅ **TikTok Pixel** - E-commerce events +✅ **Pinterest Tag** - Conversion tracking +✅ **Snapchat Pixel** - E-commerce events + +### Implementation + +**1. Keep WooCommerce Classes:** +```jsx +// customer-spa components use WooCommerce classes + +``` + +**2. Trigger WooCommerce Events:** +```typescript +// customer-spa/src/lib/tracking.ts + +export const trackAddToCart = (product: Product, quantity: number) => { + // 1. WooCommerce event (for PixelMySite and other plugins) + jQuery(document.body).trigger('added_to_cart', [ + product.id, + quantity, + product.price + ]); + + // 2. Google Analytics / GTM + window.dataLayer = window.dataLayer || []; + window.dataLayer.push({ + event: 'add_to_cart', + ecommerce: { + items: [{ + item_id: product.id, + item_name: product.name, + price: product.price, + quantity: quantity + }] + } + }); + + // 3. Facebook Pixel (if loaded by plugin) + if (typeof fbq !== 'undefined') { + fbq('track', 'AddToCart', { + content_ids: [product.id], + content_name: product.name, + value: product.price * quantity, + currency: 'USD' + }); + } +}; + +export const trackBeginCheckout = (cart: Cart) => { + // WooCommerce event + jQuery(document.body).trigger('wc_checkout_loaded'); + + // Google Analytics + window.dataLayer?.push({ + event: 'begin_checkout', + ecommerce: { + items: cart.items.map(item => ({ + item_id: item.product_id, + item_name: item.name, + price: item.price, + quantity: item.quantity + })) + } + }); +}; + +export const trackPurchase = (order: Order) => { + // WooCommerce event + jQuery(document.body).trigger('wc_order_completed', [ + order.id, + order.total + ]); + + // Google Analytics + window.dataLayer?.push({ + event: 'purchase', + ecommerce: { + transaction_id: order.id, + value: order.total, + currency: order.currency, + items: order.items.map(item => ({ + item_id: item.product_id, + item_name: item.name, + price: item.price, + quantity: item.quantity + })) + } + }); +}; +``` + +**3. Usage in Components:** +```tsx +// customer-spa/src/pages/Product/AddToCartButton.tsx + +import { trackAddToCart } from '@/lib/tracking'; + +function AddToCartButton({ product }: Props) { + const handleClick = async () => { + // Add to cart via API + await cartApi.add(product.id, quantity); + + // Track event (triggers all pixels) + trackAddToCart(product, quantity); + + // Show success message + toast.success('Added to cart!'); + }; + + return ( + + ); +} +``` + +### E-commerce Events Tracked + +``` +✅ View Product +✅ Add to Cart +✅ Remove from Cart +✅ View Cart +✅ Begin Checkout +✅ Add Shipping Info +✅ Add Payment Info +✅ Purchase +✅ Refund +``` + +### Result + +**All tracking plugins work out of the box!** +- PixelMySite listens to WooCommerce events ✅ +- Google Analytics receives dataLayer events ✅ +- Facebook/TikTok pixels fire correctly ✅ +- Store owner doesn't need to change anything ✅ + +--- + ## Feature Scope ### Phase 1: Core Commerce (MVP)