Version: 2.0.0

Template Engine

How to subscribe to the Add To Cart event in Template Engine

Add to Cart button in Template Engine will show up after the user selected a product on the page. You might want to subscribe to the Add to Cart button event to figure out which product the user wanted to add the cart/basket. This event will provide all necessary information about the product so that you can trigger your own cart/drawer with it.

Subscribe to the Add To Cart event#

You need to listen the postMessage event on window object first, then you can receive the unique id of selected product/variant after confirming the message is valid.

Here is the sample code block with explanation:

// Example template engine url.
const safeOrigin = 'https://engine.pulpoar.com';
// Your exclusive event_id to filter `postMessage` requests for safety.
// You are supposed to provide this event_id to the digitalization team with products.
const partnerEventID = 'partner_specific_id';

/*
  Example payload of `event.data`:
  {
    event_id: "0K1M2KG00K2",
    data: "P_0001" // Unique product/variant id for `add to cart` event.
  }
 */
window.addEventListener('message', function (event) {
 // Event does not come from the Plugin, you can reject it by an early return.
 if (event.origin !== safeOrigin) return;
 // Data payload is falsy or event_id does not match with yours, reject it by an early return.
 if (!event.data || event.data.event_id !== partnerEventID) return;
 // In this step, origin and event is validated and ready to use.
 const uniqueProductId = event.data.data;
 // Now you know which product/variant is clicked in order to add to the cart.
 // Call your inner add to cart function with the selected product.
 yourOwnAddToCartFunction(uniqueProductId);
});

How to trigger Shopify Cart Drawer with the Add to Cart event#

Integrations for Shopify themes might slightly change by the theme itself. Some themes might have different API's for the add to cart events. You can check the following implementation as a most common example to trigger updated cart drawer after Add to Cart event is invoked:

// Helper function to trigger the add to cart event:
const addItemToCart = async (variant_id, quantity) => {
 const itemData = {
  items: [
   {
    id: variant_id,
    quantity: quantity,
   },
  ],
 };

 await fetch('/cart/add.js', {
  method: 'POST',
  headers: {
   'Content-Type': 'application/json',
  },
  body: JSON.stringify(itemData),
 }).then(function (response) {
  if (!response.ok) {
   response.json().then((err) => alert(err.description));
  }
 });
 // Refresh the cart on the page after the cart action.
 // Note: Some themes require it to be "document.documentElement.dispatchEvent"
 // while others might just need "document.dispatchEvent".
 document.documentElement.dispatchEvent(
  new CustomEvent('cart:refresh', {
   bubbles: true,
  })
 );
 // Open side menu cart after the cart action is triggered.
 // Note: Some themes require it to be "document.documentElement.dispatchEvent"
 // while others might just need "document.dispatchEvent".
 document.documentElement.dispatchEvent(
  // Note: Some themes need the event name to be "ajaxProduct:added" instead of 'product:added'.
  new CustomEvent('product:added', {
   bubbles: true,
   detail: {
    quantity: 1,
   },
  })
 );
};

// Example template engine url.
const safeOrigin = 'https://engine.pulpoar.com';
// Your exclusive event_id to filter `postMessage` requests for safety.
// You are supposed to provide this event_id to the digitalization team with products.
const partnerEventID = 'partner_specific_id';

/*
  Example payload of `event.data`:
  {
    event_id: "0K1M2KG00K2",
    data: "P_0001" // Unique product/variant id for `add to cart` event.
  }
 */
window.addEventListener('message', function (event) {
 // Event does not come from the Plugin, you can reject it by an early return.
 if (event.origin !== safeOrigin) return;
 // Data payload is falsy or event_id does not match with yours, reject it by an early return.
 if (!event.data || event.data.event_id !== partnerEventID) return;
 // In this step, origin and event is validated and ready to use.
 const uniqueProductId = event.data.data;
 // Now you know which product/variant is clicked in order to add to the cart.
 // Call your inner add to cart function with the selected product.
 addItemToCart(uniqueProductId, 1);
});