@liquidcommerce/elements-sdk 2.3.0 → 2.4.0

package/docs/EVENTS.md

@@ -0,0 +1,532 @@
+# 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 product = event.detail.data;
+  
+  // Maybe send them a discount popup
+  showDiscountPopup(product.productName);
+  
+  // Or track in your analytics
+  analytics.track('Product Added', {
+    product: product.productName,
+    price: product.price
+  });
+});
+```
+
+## 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.productName);
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  // Product was added to cart - this is a conversion!
+  const product = event.detail.data;
+  console.log('SALE OPPORTUNITY:', product.productName, '$' + product.price);
+});
+```
+
+**🛒 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 product = event.detail.data;
+  
+  if (product.price > 100) {
+    // Show them complementary products
+    showUpsellPopup(product.productId);
+  }
+});
+```
+
+## 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.
+
+### 🛒 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');
+  }
+});
+```
+
+### 💳 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.
+
+### 📍 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;
+  
+  if (cart.total > 200 && !cart.hasPromoCode) {
+    // 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.productId]) {
+    productStats[product.productId] = {
+      name: product.productName,
+      views: 0,
+      addedToCarts: 0,
+      conversions: 0
+    };
+  }
+  
+  productStats[product.productId].views++;
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', function(event) {
+  const product = event.detail.data;
+  productStats[product.productId].addedToCarts++;
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
+  const order = event.detail.data;
+  
+  // Mark all purchased products as conversions
+  order.items.forEach(function(item) {
+    if (productStats[item.productId]) {
+      productStats[item.productId].conversions++;
+    }
+  });
+  
+  // Send stats to your analytics dashboard
+  console.log('Product Performance:', productStats);
+});
+```
+
+### 🔥 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 product = event.detail.data;
+  
+  // Show notification to other visitors
+  showNotification(`Someone just bought ${product.productName}! Only 3 left!`);
+  
+  // Update inventory count on the page
+  updateInventoryDisplay(product.productId, -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 product = event.detail.data;
+  
+  // If they added a phone, suggest a case
+  if (product.category === 'phones') {
+    showUpsell('phone-cases');
+  }
+  
+  // If cart total is close to free shipping, tell them
+  if (cart.total > 45 && cart.total < 50) {
+    showMessage("Add $" + (50 - cart.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!