Replace default GTM events with your own (GA4)

You can turn off Fast Simon’s default GA4 dataLayer events and fire your own custom events instead, using our global configuration and built‑in DOM events.

This guide covers:

• Disabling default events and using callbacks for:
  • view_item_list (impressions)
  • select_item (product click)
  • select_promotion (promotion click)
  • add_to_cart
• Listening to custom DOM events to emit your own GA4 events:
  • view_quick_add_to_cart (Quick Add click)
  • add_to_cart (on add-to-cart response)

We support both window.__fast_options and window.__fastOptions for flexibility.

---

1) Disable defaults and use callbacks to push your own events

Place this early on pages where Fast Simon widgets run (before the widgets initialize):

<script>
  // Use either "__fast_options" or "__fastOptions" (both are supported)
  window.__fast_options = window.__fast_options || {};

  // A) Disable default "view_item_list" and handle yourself
  __fast_options.avoidDefaultViewItemListEvent = true;
  __fast_options.viewItemListCallback = function (payload) {
    // payload: { items: [...], promotions?: [...], category?: 'filter' }
    // Example: send GA4 select_item for the items (as requested)
    if (payload && Array.isArray(payload.items) && payload.items.length) {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: 'select_item',
        ecommerce: { items: payload.items }
      });
    }

    // If promotions are included, you can also emit view_promotion
    if (payload && Array.isArray(payload.promotions) && payload.promotions.length) {
      window.dataLayer.push({
        event: 'view_promotion',
        ecommerce: { items: payload.promotions }
      });
    }
  };

  // B) Disable default "select_item" (product click) and emit your own event
  __fast_options.avoidDefaultSelectItemEvent = true;
  __fast_options.selectItemCallback = function (payload) {
    // payload: { items: [...] }
    if (payload && Array.isArray(payload.items) && payload.items.length) {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: 'select_item',
        ecommerce: { items: payload.items }
      });
    }
  };

  // C) Disable default "select_promotion" and emit your own event
  __fast_options.avoidDefaultSelectPromotionEvent = true;
  __fast_options.selectPromotionCallback = function (payload) {
    // payload: { items: [...] }
    if (payload && Array.isArray(payload.items) && payload.items.length) {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: 'select_promotion',
        ecommerce: { items: payload.items }
      });
    }
  };

  // D) Disable default "add_to_cart" and emit your own event
  __fast_options.avoidDefaultAddToCartEvent = true;
  __fast_options.addToCartCallback = function (payload) {
    // payload: { items: [...] }
    if (payload && Array.isArray(payload.items) && payload.items.length) {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: 'add_to_cart',
        ecommerce: { items: payload.items }
      });
    }
  };
</script>

What this does:

• Setting avoidDefault... = true prevents our default GTM event from firing.
• The corresponding ...Callback runs with a GA4-friendly payload so you can push your own dataLayer event.

Note: While select_item is typically used for product selections (clicks), the viewItemListCallback example above demonstrates how you can also emit select_item from impressions if that matches your GTM plan.

---

2) Use custom DOM events for Quick Add and Add-to-Cart response

We also dispatch CustomEvents you can listen for to send your own events.

<script>
  window.dataLayer = window.dataLayer || [];

  // Quick Add button clicked
  // Constant/event name you can listen to: 'fs-custom-events-product-quick-add-clicked'
  // Use this to send your own "view_quick_add_to_cart" event (or any custom logic)
  document.addEventListener('fs-custom-events-product-quick-add-clicked', function (evt) {
    // evt.detail may include product/context if available in your theme
    window.dataLayer.push({
      event: 'view_quick_add_to_cart',
      ecommerce: {
        // items: [{ item_id: '123', item_name: 'Product Name', quantity: 1, price: 29.99 }]
      }
    });
  });

  // Add to cart success response
  // Constant/event name: 'fs-custom-events-add-to-cart-response'
  // Detail: { cart: <platform-specific-response> }
  document.addEventListener('fs-custom-events-add-to-cart-response', function (evt) {
    const cartResponse = evt?.detail?.cart;
    // Build items from your context or cartResponse and push GA4 add_to_cart
    window.dataLayer.push({
      event: 'add_to_cart',
      ecommerce: {
        // items: [{ item_id: '123', item_name: 'Product Name', quantity: 1, price: 29.99 }]
      }
    });
  });

  // Optional: listen for add-to-cart error
  document.addEventListener('fs-custom-events-add-to-cart-error-response', function (evt) {
    const error = evt?.detail?.res;
    // Example: window.dataLayer.push({ event: 'add_to_cart_error', error });
  });
</script>

Notes:

• Quick Add event name: fs-custom-events-product-quick-add-clicked
• Add-to-cart success event name: fs-custom-events-add-to-cart-response
• Both are CustomEvent on document; subscribe once per page.

---

3) The four GA4 events you can emit

Using the snippets above, you can emit the following with your own payloads:

• select_item: via selectItemCallback or (if desired) via viewItemListCallback example above
• view_promotion: via viewItemListCallback when promotions exist
• add_to_cart: via addToCartCallback or via fs-custom-events-add-to-cart-response listener
• view_quick_add_to_cart: via fs-custom-events-product-quick-add-clicked listener

If you prefer different event names or payload schemas, adjust the dataLayer.push blocks accordingly.

---

4) Quick testing checklist

• In the browser console, set the avoidDefault flags to true and add simple console.log callbacks to verify they run.
• Trigger product impressions, clicks, promotion clicks, and add-to-cart.
• Confirm only your custom dataLayer events are sent (GTM/GA4 debug view).

Tip: We support both window.__fast_options and window.__fastOptions.