docs: Update Customer SPA Master Plan with SEO and Tracking strategies
Major Updates: 1. Architecture Clarification ✅ Fixed folder structure ✅ admin-spa/ - Admin interface ONLY ✅ customer-spa/ - Storefront + My Account in ONE app ✅ includes/Admin/ - Admin backend ✅ includes/Frontend/ - Customer backend ✅ Added tracking/ folder in customer-spa 2. SEO Strategy (NEW SECTION) ✅ Hybrid rendering approach ✅ SSR for product/category pages (SEO-critical) ✅ CSR for cart/checkout/account (no SEO needed) ✅ SEO plugin compatibility (Yoast, RankMath, etc.) ✅ WordPress renders HTML, React hydrates for interactivity ✅ Search engines see full, SEO-optimized HTML 3. Tracking & Analytics (NEW SECTION) ✅ Full compatibility with tracking plugins ✅ PixelMySite support (Facebook, TikTok, Pinterest) ✅ Google Analytics / GTM support ✅ Keep WooCommerce classes for compatibility ✅ Trigger WooCommerce events (added_to_cart, etc.) ✅ Push to dataLayer for GTM ✅ Call pixel APIs (fbq, ttq, etc.) ✅ Complete tracking implementation examples ✅ 9 e-commerce events tracked Key Decisions: - Product pages: WordPress SSR + React hydration - SEO plugins work normally (no changes needed) - Tracking plugins work out of the box - Store owner doesn't need to configure anything Result: Customer SPA is SEO-friendly and tracking-compatible!
This commit is contained in:
dwindown
@@ -24,12 +24,14 @@ This document outlines the comprehensive strategy for building WooNooW's custome
|
|||||||
|
|
||||||
1. [Architecture Overview](#architecture-overview)
|
1. [Architecture Overview](#architecture-overview)
|
||||||
2. [Deployment Modes](#deployment-modes)
|
2. [Deployment Modes](#deployment-modes)
|
||||||
3. [Feature Scope](#feature-scope)
|
3. [SEO Strategy](#seo-strategy)
|
||||||
4. [UX Best Practices](#ux-best-practices)
|
4. [Tracking & Analytics](#tracking--analytics)
|
||||||
5. [Technical Stack](#technical-stack)
|
5. [Feature Scope](#feature-scope)
|
||||||
6. [Implementation Roadmap](#implementation-roadmap)
|
6. [UX Best Practices](#ux-best-practices)
|
||||||
7. [API Requirements](#api-requirements)
|
7. [Technical Stack](#technical-stack)
|
||||||
8. [Performance Targets](#performance-targets)
|
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/
|
woonoow/
|
||||||
├── admin-spa/ # Admin interface (existing)
|
├── admin-spa/ # Admin interface ONLY
|
||||||
├── customer-spa/ # Customer frontend (NEW)
|
|
||||||
│ ├── src/
|
│ ├── 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
|
│ │ │ ├── Shop/ # Product listing
|
||||||
│ │ │ ├── Product/ # Product detail
|
│ │ │ ├── Product/ # Product detail
|
||||||
│ │ │ ├── Cart/ # Shopping cart
|
│ │ │ ├── Cart/ # Shopping cart
|
||||||
│ │ │ ├── Checkout/ # Checkout process
|
│ │ │ ├── Checkout/ # Checkout process
|
||||||
│ │ │ ├── Account/ # My Account dashboard
|
│ │ │ └── Account/ # My Account (orders, profile, addresses)
|
||||||
│ │ │ └── Orders/ # Order history
|
|
||||||
│ │ ├── components/
|
│ │ ├── components/
|
||||||
│ │ │ ├── ProductCard/
|
│ │ │ ├── ProductCard/
|
||||||
│ │ │ ├── CartDrawer/
|
│ │ │ ├── CartDrawer/
|
||||||
│ │ │ ├── CheckoutForm/
|
│ │ │ ├── CheckoutForm/
|
||||||
│ │ │ └── AddressForm/
|
│ │ │ └── AddressForm/
|
||||||
│ │ └── lib/
|
│ │ └── lib/
|
||||||
│ │ ├── api/
|
│ │ ├── api/ # API client
|
||||||
│ │ ├── cart/ # Cart state management
|
│ │ ├── cart/ # Cart state management
|
||||||
│ │ └── checkout/ # Checkout logic
|
│ │ ├── checkout/ # Checkout logic
|
||||||
|
│ │ └── tracking/ # Analytics & pixel tracking
|
||||||
│ └── public/
|
│ └── public/
|
||||||
├── includes/
|
│
|
||||||
│ ├── Admin/
|
└── includes/
|
||||||
│ └── Frontend/
|
├── Admin/ # Admin backend (serves admin-spa)
|
||||||
│ ├── Shortcodes/ # [woonoow_cart], [woonoow_checkout]
|
│ ├── AdminController.php
|
||||||
│ ├── SPA/ # Full SPA mode handler
|
│ └── MenuManager.php
|
||||||
│ └── Api/ # Customer API endpoints
|
│
|
||||||
└── woonoow.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
|
## 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
|
||||||
|
<?php
|
||||||
|
// WordPress renders full HTML (SEO-friendly)
|
||||||
|
get_header();
|
||||||
|
|
||||||
|
$product = wc_get_product( get_the_ID() );
|
||||||
|
?>
|
||||||
|
|
||||||
|
<!-- Server-rendered HTML for SEO -->
|
||||||
|
<div id="woonoow-product" data-product-id="<?php echo $product->get_id(); ?>">
|
||||||
|
<h1><?php echo $product->get_name(); ?></h1>
|
||||||
|
<div class="price"><?php echo $product->get_price_html(); ?></div>
|
||||||
|
<div class="description"><?php echo $product->get_description(); ?></div>
|
||||||
|
|
||||||
|
<!-- SEO plugins inject meta tags here -->
|
||||||
|
<?php do_action('woocommerce_after_single_product'); ?>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<?php
|
||||||
|
get_footer();
|
||||||
|
// React hydrates this div for interactivity (add to cart, variations, etc.)
|
||||||
|
?>
|
||||||
|
```
|
||||||
|
|
||||||
|
**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
|
||||||
|
<button
|
||||||
|
className="single_add_to_cart_button" // WooCommerce class
|
||||||
|
data-product_id="123" // WooCommerce data attr
|
||||||
|
onClick={handleAddToCart}
|
||||||
|
>
|
||||||
|
Add to Cart
|
||||||
|
</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**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 (
|
||||||
|
<button
|
||||||
|
className="single_add_to_cart_button"
|
||||||
|
onClick={handleClick}
|
||||||
|
>
|
||||||
|
Add to Cart
|
||||||
|
</button>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
## Feature Scope
|
||||||
|
|
||||||
### Phase 1: Core Commerce (MVP)
|
### Phase 1: Core Commerce (MVP)
|
||||||
|
|||||||
Reference in New Issue
Block a user