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)
|
||||
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
|
||||
<?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
|
||||
|
||||
### Phase 1: Core Commerce (MVP)
|
||||
|
||||
Reference in New Issue
Block a user