Automatic event triggers

Storefront JS API can help you with developing storefront customizations. One of the most useful and often required tools is automatic triggers. Automatic triggers work like event handlers, calling the code inside when a specific event happens on the storefront. With event triggers, you don't have to write manually and test code for tracking events like page DOM load, customer login, customer cart change, etc.

Enable JS API on the storefront

The methods listed below require JS API to be loaded on the page. Read more on how to enable JS API.

Ecwid.OnAPILoaded()

This function triggers your code inside when Storefront JS API fully loads on the storefront page. It also ensures that the JS API is loaded before your code relying on it starts working. We recommend calling all JavaScript code related to the Ecwid storefront from inside this method.

Code example:

Ecwid.OnAPILoaded.add(function() {
    console.log("Ecwid storefront JS API has loaded");
});

Use case for other triggers and methods:

Ecwid.OnAPILoaded.add(function() {
    console.log("JS API is loaded");
    console.log("Ecwid store ID: "+Ecwid.getOwnerId());
    
    Ecwid.OnPageLoaded.add(function(page) {
        console.log("Page DOM is loaded");
        console.log("Page type is: "+page.type)
    });
});

// prints
// 
// JS API is loaded
// Ecwid store ID: 15695068
// Page DOM is loaded
// Page type is: SITE

When this method triggers, the website DOM is not yet loaded, so use it to load scripts that don't rely on specific page content.

Ecwid.OnPageLoad

This event runs when the page DOM is loaded. Please note that it doesn't wait for the Ecwid product browser to fully load.

Code example:

Ecwid.OnPageLoad.add(function() {
    console.log("Page DOM has just loaded");
});

Ecwid.OnPageLoaded

This method is different from the OnPageLoad. It runs when the page DOM with the Ecwid product browser is loaded and is ready for customization.

It contains a callback function with page argument containing information about a loaded page.

Code examples:

Ecwid.OnPageLoaded.add(function(page){
  console.log(JSON.stringify(page));
});

// prints
// 
// {
//   "type":"PRODUCT",
//   "categoryId":0,
//   "hasPrevious":false,
//   "mainCategoryId":0,
//   "name":"Desk Black 101x50x76.5 cm Engineered Wood",
//   "nameTranslated":{
//     "cs":"",
//     "en":"Desk Black 101x50x76.5 cm Engineered Wood"
//   },
//   "productId":561386461
// }

Ecwid.OnPageLoaded.add(function(page) {
    if (page.type == "CART") {
      // do something ...
  }
});

page callback fields

FilterParameters

Ecwid.OnSetProfile

This method allows tracking when customers log in and out on the storefront. It contains a callback function with customer argument when a customer logs in, and null if a customer has logged out.

Code example:

Ecwid.OnSetProfile.add(function(customer){
	console.log(customer.email);
})

// prints
// "[email protected]"

Ecwid.OnCartChanged

This event allows tracking any cart changes excluding the payment method selection. It contains a callback function with a cart argument, that has information about the cart after the change.

Code example:

Ecwid.OnCartChanged.add(function(cart){
    console.log(JSON.stringify(cart));
});

// prints
// 
// {
// 	"id":"TJ6VG",
// 	"cartId":"99E7E224-5F6F-4C00-BFE9-9F72F2B5A471",
// 	"orderId":506524300,
// 	"items":[...],
// 	"productsQuantity":4,
// 	"shippingMethod":"Standard shipping",
// 	"shippingPerson":{},
// 	"weight":4
// }

Full list of Ecwid.OnCartChanged event triggers :

• Cart is initialized, synced or cleared
• Product added, updated (increased quantity, changed selected options) or removed
• Discount coupon or discount is applied or removed
• Shipping address is added or updated
• Shipping method is selected or changed

Ecwid.OnProductOptionsChanged

This event allows tracking of changed product options on product pages. It contains a callback function with productid argument, containing ID of the changed product.

Code example:

Ecwid.OnProductOptionsChanged.add(function(productid) {
   console.log("Options changed, product id: " + productid);    
});

// prints
// Options changed, product id: 123456

Ecwid.OnOrderPlaced

This event allows tracking placed orders on the storefront and receiving order details in a callback function with an order argument.

Code example:

Ecwid.OnAPILoaded.add(() => {
    Ecwid.OnOrderPlaced.add((order) => {
        console.log(order.total);
    });
});

// prints
// 829

order callback argument

OrderItems

ProductInfo

PersonInfo

CustomerInfo

OrderExtraFieldsInfo

Ecwid.OnPageSwitch

This method allows tracking and preventing page switches on the storefront. It is triggered when a user is about to switch a page. The method works synchronously and contains a page argument in its callback function.

Use it to identify the page where users go and prevent page loading by returning a false value.

Code example:

Ecwid.OnPageSwitch.add(function(page) {
    if (page.type === "PRODUCT") {
        window.location.href = "index.html?type=product&id=" + page.productId
        return false
    } else if (page.type === "CATEGORY") {
        window.location.href = "index.html?type=category&id=" + page.categoryId
        return false
    }
})

window.instantsite.onTileLoaded

Ecwid Instant Site dynamically loads and unloads its sections depending on what customers currently see. This method allows you to call your JS code when a specific section (called "tile" in the function) is loaded.

Code example:

document.addEventListener("DOMContentLoaded", function() {
	window.instantsite.onTileLoaded.add(function (tile) {
		if (tile === 'tile-id') {
			document.getElementById("tile-id").innerHTML = '<iframe src=""></iframe>'; //add custom iframe
		}
	});
});

window.instantsite.onTileUnloaded

Ecwid Instant Site dynamically loads and unloads its sections depending on what customers currently see. This method allows you to call your JS code when a specific section (called "tile" in the function) is loaded.

document.addEventListener("DOMContentLoaded", function() {
	window.instantsite.onTileUnloaded.add(function (tile) {
		if (tile === 'tile-id') {
			document.getElementById("tile-id").innerHTML = ''; //remove Custom iframe
		}
	});
});