@liquidcommerce/elements-sdk 2.3.0 → 2.4.1

package/docs/EVENTS.md

@@ -0,0 +1,765 @@
+# Elements SDK Events - Partner Implementation Guide
+
+> **Browser Support**: This SDK supports 2018+ browsers (Chrome 66+, Firefox 60+, Safari 12+) with comprehensive polyfills. See `docs/BROWSER_SUPPORT.md` for details.
+
+## What Are Events and Why Use Them?
+
+Events are real-time notifications that tell you exactly what your customers are doing on your site. Think of them as your digital sales assistant that whispers in your ear every time a customer looks at a product, adds something to cart, or starts checkout.
+
+**Business Benefits:**
+- **Track Revenue Impact**: See which products drive the most sales
+- **Optimize Conversion**: Identify where customers drop off
+- **Personalize Experience**: Trigger custom actions based on customer behavior
+- **Measure Performance**: Get real metrics on your e-commerce funnel
+- **Automate Marketing**: Send targeted emails/SMS based on customer actions
+
+## How It Works
+
+When customers interact with your LiquidCommerce elements, events automatically fire. You simply "listen" for these events and take action:
+
+```javascript
+// Example: When someone adds to cart, send them a discount code
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  // Customer just added a product to cart!
+  const data = event.detail.data;
+  
+  // Maybe send them a discount popup
+  showDiscountPopup(data.identifier);
+  
+  // Or track in your analytics
+  analytics.track('Product Added', {
+    identifier: data.identifier,
+    quantity: data.quantity,
+    upc: data.upc
+  });
+});
+```
+
+## Quick Implementation Guide
+
+### Step 1: Choose Your Goal
+What do you want to achieve? Pick one:
+
+**🎯 Track Sales Performance**
+```javascript
+// Track when products are viewed and added to cart
+window.addEventListener('lce:actions.product_loaded', function(event) {
+  // Product was viewed - track in your analytics
+  const product = event.detail.data;
+  console.log('Customer viewed:', product.name);
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  // Product was added to cart - this is a conversion!
+  const data = event.detail.data;
+  console.log('SALE OPPORTUNITY:', data.identifier, 'qty:', data.quantity);
+});
+```
+
+**🛒 Recover Abandoned Carts**
+```javascript
+// Detect when someone opens cart but doesn't buy
+window.addEventListener('lce:actions.cart_opened', function(event) {
+  // Start a timer - if they don't complete purchase in 10 minutes, send email
+  setTimeout(function() {
+    sendAbandonedCartEmail();
+  }, 10 * 60 * 1000); // 10 minutes
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
+  // They bought! Cancel the abandoned cart email
+  cancelAbandonedCartEmail();
+});
+```
+
+**💰 Maximize Revenue**
+```javascript
+// Offer upsells when they add expensive items
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  const data = event.detail.data;
+  
+  // Trigger upsell based on product identifier
+  showUpsellPopup(data.identifier);
+});
+```
+
+## Step 2: Complete Event List & What They Mean
+
+### 🚀 SDK Lifecycle Events
+```javascript
+// When SDK is ready to use
+'lce:actions.client_ready' // → "SDK is initialized and ready to use"
+```
+
+**Example Usage:**
+```javascript
+window.addEventListener('lce:actions.client_ready', function(event) {
+  const { isReady, message, timestamp, version } = event.detail.data;
+  console.log('SDK Ready:', version);
+  // Now safe to call SDK methods
+});
+```
+
+### 🛍️ Product Events (Track Customer Interest)
+```javascript
+// When a customer views a product
+'lce:actions.product_loaded' // → "Customer is interested in this product"
+
+// When they add to cart
+'lce:actions.product_add_to_cart' // → "Hot lead! Customer wants to buy"
+
+// When they change quantity
+'lce:actions.product_quantity_increase' // → "Customer wants more"
+'lce:actions.product_quantity_decrease' // → "Customer wants less"
+
+// When they change options
+'lce:actions.product_size_changed' // → "Customer has size preferences"
+'lce:actions.product_fulfillment_type_changed' // → "Delivery preference changed"
+'lce:actions.product_fulfillment_changed' // → "Customer selected specific retailer/fulfillment"
+```
+
+**Note on Personalization:** Product personalization (engraving) is added during the add-to-cart action. The personalization is included in the `product_add_to_cart` event data. Once in cart, use `cart_item_engraving_updated` to track changes.
+
+#### Product Details Event Data
+When `lce:actions.product_loaded` fires, you get comprehensive product information:
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', function(event) {
+  const product = event.detail.data;
+  
+  // Basic Information
+  console.log(product.id);              // Product ID
+  console.log(product.name);            // Product name
+  console.log(product.brand);           // Brand name
+  console.log(product.category);        // Category
+  console.log(product.catPath);         // Category path
+  console.log(product.classification);  // Product classification
+  console.log(product.type);            // Product type
+  console.log(product.subType);         // Product sub-type
+  console.log(product.salsifyGrouping); // Salsify grouping ID
+  
+  // Visual Assets
+  console.log(product.mainImage);       // Main product image URL
+  console.log(product.images);          // Array of all product images
+  
+  // Product Attributes
+  console.log(product.region);          // Region (e.g., "Napa Valley")
+  console.log(product.country);         // Country of origin
+  console.log(product.material);        // Material type
+  console.log(product.abv);             // Alcohol by volume
+  console.log(product.proof);           // Proof
+  console.log(product.age);             // Age statement
+  console.log(product.color);           // Color description
+  console.log(product.flavor);          // Flavor profile
+  console.log(product.variety);         // Variety (e.g., "Cabernet Sauvignon")
+  console.log(product.appellation);     // Appellation
+  console.log(product.vintage);         // Vintage year
+  
+  // Descriptions
+  console.log(product.description);     // Plain text description
+  console.log(product.htmlDescription); // HTML formatted description
+  console.log(product.tastingNotes);    // Tasting notes
+  
+  // Pricing
+  console.log(product.priceInfo);       // { min, max, avg } pricing across fulfillments
+  
+  // Available Sizes & Fulfillments
+  console.log(product.sizes);           // All available sizes with fulfillment options
+  console.log(product.selectedSizeId);  // Currently selected size
+  console.log(product.selectedFulfillmentId);   // Currently selected fulfillment
+  console.log(product.selectedFulfillmentType); // 'shipping' or 'onDemand'
+});
+```
+
+**Use Cases:**
+- **Rich Analytics**: Track which product attributes drive conversions
+- **Personalized Recommendations**: Suggest similar products based on variety, region, or flavor
+- **Content Display**: Show detailed product information on your custom UI
+- **Search & Filtering**: Build custom search based on product attributes
+
+### 🛒 Cart Events (Track Purchase Intent)
+```javascript
+// Cart lifecycle
+'lce:actions.cart_loaded' // → "Cart data has been loaded and is ready"
+'lce:actions.cart_opened' // → "Customer is reviewing their purchase"
+'lce:actions.cart_closed' // → "Customer might be comparison shopping"
+
+// Cart changes
+'lce:actions.cart_updated' // → "Customer modified their order"
+'lce:actions.cart_reset' // → "Customer cleared everything - intervention needed!"
+'lce:actions.cart_failed' // → "Cart operation failed"
+
+// Item management
+'lce:actions.cart_item_added' // → "Customer committed to another product"
+'lce:actions.cart_item_removed' // → "Customer changed their mind"
+'lce:actions.cart_item_quantity_increase' // → "Customer added more of an item"
+'lce:actions.cart_item_quantity_decrease' // → "Customer reduced item quantity"
+'lce:actions.cart_item_engraving_updated' // → "Customer updated/removed item personalization"
+```
+
+**Personalization Events:**
+```javascript
+// Track when customers add or modify personalization
+window.addEventListener('lce:actions.cart_item_engraving_updated', function(event) {
+  const { identifier, engravingLines, hasEngraving } = event.detail.data;
+  
+  if (hasEngraving && engravingLines.length > 0) {
+    console.log(`Personalization added/updated: ${engravingLines.join(', ')}`);
+  } else {
+    console.log('Personalization removed from item');
+  }
+});
+```
+
+#### Cart Details Event Data
+When `lce:actions.cart_loaded` or `lce:actions.cart_updated` fires, you get complete cart information:
+
+```javascript
+window.addEventListener('lce:actions.cart_loaded', function(event) {
+  const cart = event.detail.data;
+  
+  // Cart Identification
+  console.log(cart.id);                 // Cart ID
+  console.log(cart.promoCode);          // Applied promo code (if any)
+  
+  // Cart Items
+  console.log(cart.items);              // Object with all cart items
+  console.log(cart.itemCount);          // Total number of items in cart
+  
+  // Each item contains:
+  Object.values(cart.items).forEach(item => {
+    console.log(item.id);               // Cart item ID
+    console.log(item.name);             // Product name
+    console.log(item.brand);            // Brand
+    console.log(item.salsifyGrouping);  // Salsify grouping ID
+    console.log(item.catPath);          // Category path
+    console.log(item.size);             // Size description
+    console.log(item.volume);           // Volume
+    console.log(item.uom);              // Unit of measure
+    console.log(item.pack);             // Is pack (boolean)
+    console.log(item.packDesc);         // Pack description
+    console.log(item.container);        // Container type
+    console.log(item.containerType);    // Container type classification
+    console.log(item.price);            // Total price (unitPrice × quantity)
+    console.log(item.unitPrice);        // Price per unit
+    console.log(item.quantity);         // Quantity
+    console.log(item.maxQuantity);      // Maximum allowed quantity
+    console.log(item.mainImage);        // Product image URL
+    console.log(item.upc);              // UPC code
+    console.log(item.sku);              // SKU
+    console.log(item.partNumber);       // Part number
+    console.log(item.retailerId);       // Retailer ID
+    console.log(item.fulfillmentId);    // Fulfillment ID
+    console.log(item.attributes);       // Item attributes (engraving, etc.)
+  });
+  
+  // Location Information
+  console.log(cart.location.placesId);           // Google Places ID
+  console.log(cart.location.address);            // Address object
+  console.log(cart.location.coordinates);        // Lat/long coordinates
+  
+  // Financial Breakdown
+  console.log(cart.amounts.subtotal);            // Subtotal
+  console.log(cart.amounts.deliveryFee);         // Delivery fee
+  console.log(cart.amounts.shippingFee);         // Shipping fee
+  console.log(cart.amounts.platformFee);         // Platform fee
+  console.log(cart.amounts.engravingFee);        // Engraving/personalization fee
+  console.log(cart.amounts.discounts);           // Total discounts
+  console.log(cart.amounts.giftCardTotal);       // Gift card total applied
+  console.log(cart.amounts.total);               // Final total
+  
+  // Timestamps
+  console.log(cart.createdAt);          // When cart was created
+  console.log(cart.updatedAt);          // Last update timestamp
+});
+```
+
+**Use Cases:**
+- **Abandoned Cart Recovery**: Track cart value and items for targeted recovery campaigns
+- **Revenue Analytics**: Monitor average cart value, most popular items, cart composition
+- **Inventory Management**: Track which products are frequently added/removed
+- **Pricing Analysis**: Analyze impact of fees, discounts, and gift cards on cart totals
+
+### 💳 Checkout Events (Track Purchase Process)
+```javascript
+// Checkout lifecycle
+'lce:actions.checkout_loaded' // → "Checkout data has been loaded and is ready"
+'lce:actions.checkout_opened' // → "Customer is ready to buy!"
+'lce:actions.checkout_closed' // → "Customer left checkout"
+'lce:actions.checkout_failed' // → "Checkout operation failed"
+
+// Checkout submission
+'lce:actions.checkout_submit_started' // → "Payment processing..."
+'lce:actions.checkout_submit_completed' // → "SALE COMPLETED! 🎉"
+'lce:actions.checkout_submit_failed' // → "Sale lost - fix the issue!"
+
+// Form updates
+'lce:actions.checkout_customer_information_updated' // → "Customer filling out details"
+'lce:actions.checkout_billing_information_updated' // → "Payment info being entered"
+'lce:actions.checkout_gift_information_updated' // → "Gift recipient info updated"
+
+// Checkout options
+'lce:actions.checkout_is_gift_toggled' // → "Customer toggled gift option"
+'lce:actions.checkout_billing_same_as_shipping_toggled' // → "Customer toggled billing address option"
+'lce:actions.checkout_marketing_preferences_toggled' // → "Customer updated marketing preferences"
+
+// Item management in checkout
+'lce:actions.checkout_item_removed' // → "Customer removed item from checkout"
+'lce:actions.checkout_item_quantity_increase' // → "Customer increased item quantity in checkout"
+'lce:actions.checkout_item_quantity_decrease' // → "Customer decreased item quantity in checkout"
+'lce:actions.checkout_item_engraving_updated' // → "Customer removed personalization in checkout"
+
+// Tips (for on-demand delivery)
+'lce:actions.checkout_tip_updated' // → "Customer updated delivery tip"
+```
+
+**Important Note on Checkout Personalization:**  
+Personalization cannot be edited during checkout - only removed. This is by design to prevent order processing complications. If a customer wants to modify personalization, they must return to the cart. The checkout only displays personalization details and provides a remove option.
+
+#### Checkout Details Event Data
+When you call `actions.checkout.getDetails()`, you get comprehensive checkout information:
+
+**Note:** The `lce:actions.checkout_loaded` event only contains `{ cartId: string }`. To get full checkout details, use `actions.checkout.getDetails()`.
+
+```javascript
+// Get full checkout details via action
+const checkout = actions.checkout.getDetails();
+  
+  // Checkout Identification
+  console.log(checkout.cartId);                    // Associated cart ID
+  
+  // Checkout Status Flags
+  console.log(checkout.acceptedAccountCreation);   // Customer accepted account creation
+  console.log(checkout.hasAgeVerify);              // Age verification required
+  console.log(checkout.hasSubstitutionPolicy);     // Substitution policy accepted
+  console.log(checkout.isGift);                    // Order is a gift
+  console.log(checkout.billingSameAsShipping);     // Billing address same as shipping
+  console.log(checkout.hasPromoCode);              // Promo code applied
+  console.log(checkout.hasGiftCards);              // Gift cards applied
+  
+  // Marketing Preferences
+  console.log(checkout.marketingPreferences.canEmail); // Email opt-in status
+  console.log(checkout.marketingPreferences.canSms);   // SMS opt-in status
+  
+  // Order Summary
+  console.log(checkout.itemCount);                 // Total items in checkout
+  
+  // Financial Breakdown
+  console.log(checkout.amounts.subtotal);          // Subtotal
+  console.log(checkout.amounts.deliveryFee);       // Delivery fee
+  console.log(checkout.amounts.shippingFee);       // Shipping fee
+  console.log(checkout.amounts.platformFee);       // Platform fee
+  console.log(checkout.amounts.engravingFee);      // Engraving/personalization fee
+  console.log(checkout.amounts.discounts);         // Total discounts
+  console.log(checkout.amounts.giftCardTotal);     // Gift card total applied
+  console.log(checkout.amounts.tax);               // Tax amount
+  console.log(checkout.amounts.bottleDeposits);    // Bottle deposit fees
+  console.log(checkout.amounts.total);             // Final total
+  
+  // Checkout Items (detailed product information)
+  console.log(checkout.items);                     // Object with all checkout items
+  
+// Each checkout item contains comprehensive details:
+Object.values(checkout.items).forEach(item => {
+  console.log(item.cartItemId);        // Cart item ID
+  console.log(item.liquidId);          // Liquid ID
+  console.log(item.variantId);         // Variant ID
+  console.log(item.name);              // Product name
+  console.log(item.brand);             // Brand
+  console.log(item.salsifyGrouping);   // Salsify grouping ID
+  console.log(item.catPath);           // Category path
+  
+  // Size & Container Information
+  console.log(item.size);              // Size description
+  console.log(item.volume);            // Volume
+  console.log(item.uom);               // Unit of measure
+  console.log(item.pack);              // Is pack (boolean)
+  console.log(item.packDesc);          // Pack description
+  console.log(item.container);         // Container type
+  console.log(item.containerType);     // Container type classification
+  
+  // Product Attributes
+  console.log(item.proof);             // Proof
+  console.log(item.abv);               // Alcohol by volume
+  
+  // Pricing
+  console.log(item.price);             // Total price (unitPrice × quantity)
+  console.log(item.unitPrice);         // Price per unit
+  console.log(item.unitTax);           // Tax per unit
+  console.log(item.bottleDeposits);    // Bottle deposit fees
+  console.log(item.quantity);          // Quantity
+  
+  // Identifiers
+  console.log(item.upc);               // UPC code
+  console.log(item.sku);               // SKU
+  console.log(item.partNumber);        // Part number
+  
+  // Fulfillment Information
+  console.log(item.retailerId);        // Retailer ID
+  console.log(item.retailerName);      // Retailer name
+  console.log(item.fulfillmentId);     // Fulfillment ID
+  console.log(item.expectationDetail); // Delivery expectation details
+  
+  // Visual Assets
+  console.log(item.mainImage);         // Product image URL
+  
+  // Item Attributes (engraving, etc.)
+  console.log(item.attributes);        // Item attributes object
+});
+```
+
+**Use Cases:**
+- **Order Analytics**: Track checkout completion rates, average order values, popular items
+- **Marketing Optimization**: Analyze opt-in rates, gift order patterns, promo code effectiveness
+- **Revenue Tracking**: Monitor tax collection, fees, discounts, and gift card usage
+- **Customer Insights**: Understand purchasing patterns, preferred retailers, delivery preferences
+- **Compliance**: Track age verification requirements, substitution policy acceptance
+
+### 📍 Address Events (Track Shipping Preferences)
+```javascript
+'lce:actions.address_updated' // → "Customer entered shipping address"
+'lce:actions.address_cleared' // → "Customer removed address"
+'lce:actions.address_failed' // → "Address validation failed"
+```
+
+### 🔔 **NEW: Action Feedback Events** (Track Action Success/Failure)
+
+These events fire when programmatic actions succeed or fail, giving you complete control over user feedback:
+
+#### 🛒 **Cart Action Feedback**
+```javascript
+// Product addition feedback
+'lce:actions.cart_product_add_success' // → "Products successfully added to cart"
+// Data: { itemsAdded: number, identifiers: string[] }
+
+'lce:actions.cart_product_add_failed' // → "Products could not be added to cart" 
+// Data: { identifiers: string[], error: string }
+
+// Promo code feedback
+'lce:actions.cart_promo_code_applied' // → "Promo code worked - show success!"
+// Data: { applied: true, discountAmount?: number, newTotal?: number }
+
+'lce:actions.cart_promo_code_removed' // → "Promo code removed successfully"
+// Data: { applied: false }
+
+'lce:actions.cart_promo_code_failed' // → "Promo code didn't work - show error"
+// Data: { attempted: true, error: string }
+```
+
+#### 💳 **Checkout Action Feedback**
+```javascript
+// Product addition feedback
+'lce:actions.checkout_product_add_success' // → "Products added to checkout successfully"
+// Data: { itemsAdded: number, identifiers: string[] }
+
+'lce:actions.checkout_product_add_failed' // → "Could not add products to checkout"
+// Data: { identifiers: string[], error: string }
+
+// Promo code feedback
+'lce:actions.checkout_promo_code_applied' // → "Checkout discount applied!"
+// Data: { applied: true, discountAmount?: number, newTotal?: number }
+
+'lce:actions.checkout_promo_code_removed' // → "Checkout discount removed"
+// Data: { applied: false }
+
+'lce:actions.checkout_promo_code_failed' // → "Checkout discount failed"
+// Data: { attempted: true, error: string }
+
+// Gift card feedback  
+'lce:actions.checkout_gift_card_applied' // → "Gift card applied successfully!"
+// Data: { applied: true, newTotal?: number }
+
+'lce:actions.checkout_gift_card_removed' // → "Gift card removed"
+// Data: { applied: false }
+
+'lce:actions.checkout_gift_card_failed' // → "Gift card could not be applied"
+// Data: { attempted: true, error: string }
+```
+
+#### 🔒 **Security Note**
+Action feedback events **never expose sensitive information** like promo codes or gift card codes. This prevents malicious scripts from stealing sensitive data while still providing rich feedback for legitimate developers.
+
+**Example: Secure Action Feedback**
+```javascript
+// Fire the action (simple)
+await actions.cart.applyPromoCode('SECRET20');
+
+// Get feedback (secure) 
+window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
+  const { applied, discountAmount, newTotal } = event.detail.data;
+  // ✅ You get: success status, discount amount, new total
+  // 🚫 You DON'T get: 'SECRET20' (secure!)
+  
+  showSuccessMessage(`🎉 Discount applied! You saved $${discountAmount}!`);
+  updateCartTotal(newTotal);
+});
+```
+
+## Step 3: Real-World Implementation Examples
+
+### 🔔 **NEW Example: Smart Action Feedback with Perfect UX**
+```javascript
+// Perfect promo code experience with action feedback
+async function applyPromoCodeWithFeedback(code) {
+  // Show loading state
+  showLoadingMessage('Applying promo code...');
+  
+  // Set up event listeners BEFORE firing action
+  const successHandler = (event) => {
+    const { applied, discountAmount, newTotal } = event.detail.data;
+    hideLoadingMessage();
+    showSuccessMessage(`🎉 Success! You saved $${discountAmount}!`);
+    updatePriceDisplay(newTotal);
+    
+    // Track successful promo usage
+    analytics.track('Promo Applied', { 
+      discount: discountAmount,
+      newTotal: newTotal 
+    });
+    
+    // Clean up
+    cleanup();
+  };
+  
+  const failureHandler = (event) => {
+    const { attempted, error } = event.detail.data;
+    hideLoadingMessage();
+    showErrorMessage('Promo code could not be applied. Please try again.');
+    
+    // Track failed attempts (for optimization)
+    analytics.track('Promo Failed', { error: error });
+    
+    // Maybe suggest alternatives
+    suggestAlternativePromos();
+    
+    // Clean up
+    cleanup();
+  };
+  
+  const cleanup = () => {
+    window.removeEventListener('lce:actions.cart_promo_code_applied', successHandler);
+    window.removeEventListener('lce:actions.cart_promo_code_failed', failureHandler);
+  };
+  
+  // Attach listeners
+  window.addEventListener('lce:actions.cart_promo_code_applied', successHandler);
+  window.addEventListener('lce:actions.cart_promo_code_failed', failureHandler);
+  
+  // Fire the action
+  await actions.cart.applyPromoCode(code);
+}
+
+// Usage: Perfect UX every time!
+applyPromoCodeWithFeedback('SAVE20');
+```
+
+### 🎯 Example 1: Boost Your Sales with Smart Promotions
+```javascript
+// Automatically offer discounts for high-value carts
+window.addEventListener('lce:actions.cart_updated', function(event) {
+  const cart = event.detail.data.current;
+  
+  if (cart.amounts.total > 200 && !cart.promoCode) {
+    // Show them a 10% off popup
+    showPopup("Get 10% off orders over $200! Use code: SAVE10");
+  }
+});
+
+// Track which products make people abandon checkout
+window.addEventListener('lce:actions.checkout_opened', function(event) {
+  window.checkoutStartTime = new Date();
+});
+
+window.addEventListener('lce:actions.checkout_closed', function(event) {
+  // If they close checkout without buying, they abandoned
+  if (window.checkoutStartTime) {
+    const timeSpent = new Date() - window.checkoutStartTime;
+    console.log('Checkout abandoned after', timeSpent/1000, 'seconds');
+    // Send this data to your analytics to find problem products
+  }
+});
+```
+
+### 📧 Example 2: Automated Email Marketing
+```javascript
+// Build an email list from cart abandoners
+window.addEventListener('lce:actions.cart_opened', function(event) {
+  // Customer opened cart - start tracking
+  window.cartOpenTime = new Date();
+  window.cartItems = event.detail.data.items;
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
+  // They bought! No need for abandonment email
+  window.cartOpenTime = null;
+});
+
+// Check every 5 minutes if cart was abandoned
+setInterval(function() {
+  if (window.cartOpenTime) {
+    const timeSinceOpen = new Date() - window.cartOpenTime;
+    if (timeSinceOpen > 15 * 60 * 1000) { // 15 minutes
+      // Send abandonment email with cart items
+      sendAbandonmentEmail(window.cartItems);
+      window.cartOpenTime = null; // Don't send again
+    }
+  }
+}, 5 * 60 * 1000);
+```
+
+### 📊 Example 3: Track Your Best-Performing Products
+```javascript
+// Keep a running tally of product performance
+let productStats = {};
+
+window.addEventListener('lce:actions.product_loaded', function(event) {
+  const product = event.detail.data;
+  
+  // Initialize stats if first time seeing this product
+  if (!productStats[product.id]) {
+    productStats[product.id] = {
+      name: product.name,
+      views: 0,
+      addedToCarts: 0,
+      conversions: 0
+    };
+  }
+  
+  productStats[product.id].views++;
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  const data = event.detail.data;
+  // Note: product_add_to_cart only has identifier, not full product details
+  if (productStats[data.identifier]) {
+    productStats[data.identifier].addedToCarts++;
+  }
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
+  const order = event.detail.data;
+  console.log('Order completed:', order.orderNumber, 'Total:', order.orderTotal);
+  
+  // Send stats to your analytics dashboard
+  console.log('Product Performance:', productStats);
+  
+  // Track conversion in analytics
+  analytics.track('Purchase', {
+    orderNumber: order.orderNumber,
+    total: order.orderTotal
+  });
+});
+```
+
+### 🔥 Example 4: Create Urgency with Live Updates
+```javascript
+// Show live activity to create FOMO (Fear of Missing Out)
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  const data = event.detail.data;
+  
+  // Show notification to other visitors
+  showNotification(`Someone just bought product ${data.identifier}! Only 3 left!`);
+  
+  // Update inventory count on the page
+  updateInventoryDisplay(data.identifier, -1);
+});
+
+window.addEventListener('lce:actions.cart_opened', function(event) {
+  // Show how many people are currently viewing this product
+  showViewerCount("👀 5 people are looking at this right now");
+});
+```
+
+## Common Use Cases & How to Implement
+
+### 🛒 **Cart Abandonment Recovery**
+**The Problem**: 70% of carts are abandoned
+**The Solution**: Automatic follow-up based on events
+
+```javascript
+// Set up cart abandonment tracking
+let abandonmentTimer;
+
+window.addEventListener('lce:actions.cart_opened', function() {
+  // Reset timer each time they open cart
+  clearTimeout(abandonmentTimer);
+  
+  abandonmentTimer = setTimeout(function() {
+    // After 30 minutes of inactivity, trigger recovery
+    triggerCartRecovery();
+  }, 30 * 60 * 1000);
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', function() {
+  // They completed purchase - cancel recovery
+  clearTimeout(abandonmentTimer);
+});
+
+function triggerCartRecovery() {
+  // Send email, show popup, etc.
+  console.log("Time to recover this cart!");
+}
+```
+
+### 📈 **Revenue Optimization**
+**The Goal**: Increase average order value
+**The Method**: Smart upselling based on behavior
+
+```javascript
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  const data = event.detail.data;
+  
+  // Offer upsells based on product identifier
+  const upsellMap = {
+    'phone-001': 'phone-cases',
+    'laptop-001': 'laptop-accessories'
+  };
+  
+  if (upsellMap[data.identifier]) {
+    showUpsell(upsellMap[data.identifier]);
+  }
+  
+  // Check if cart is close to free shipping threshold
+  const cart = actions.cart.getDetails();
+  if (cart.amounts.total > 45 && cart.amounts.total < 50) {
+    showMessage("Add $" + (50 - cart.amounts.total) + " more for FREE shipping!");
+  }
+});
+```
+
+### 🎯 **Conversion Tracking**
+**The Need**: Measure what's working
+**The Implementation**: Track the entire funnel
+
+```javascript
+// Track the complete conversion funnel
+const funnelSteps = {
+  productView: 0,
+  addToCart: 0,
+  cartView: 0,
+  checkoutStart: 0,
+  purchase: 0
+};
+
+window.addEventListener('lce:actions.product_loaded', () => funnelSteps.productView++);
+window.addEventListener('lce:actions.product_add_to_cart', () => funnelSteps.addToCart++);
+window.addEventListener('lce:actions.cart_opened', () => funnelSteps.cartView++);
+window.addEventListener('lce:actions.checkout_opened', () => funnelSteps.checkoutStart++);
+window.addEventListener('lce:actions.checkout_submit_completed', () => funnelSteps.purchase++);
+
+// Send to your analytics every 10 minutes
+setInterval(() => {
+  console.log('Conversion Funnel:', funnelSteps);
+  // Send to your dashboard/analytics
+}, 10 * 60 * 1000);
+```
+
+## Getting Started in 5 Minutes
+
+1. **Pick one goal** from the examples above
+2. **Copy the code** into your website
+3. **Replace the console.log** with your actual actions (send email, show popup, etc.)
+4. **Test it** by going through the flow yourself
+5. **Monitor the results** and adjust as needed
+
+**Need help?** The events automatically work once LiquidCommerce Elements are on your page. Just add the JavaScript code and you're ready to go!