NAV

Logic and code

Add Ecwid to the site

Add Ecwid storefront to your website

<div id="my-store-1003"></div><div> <script type="text/javascript" src="https://app.ecwid.com/script.js?1003" charset="utf-8"></script><script type="text/javascript"> xProductBrowser("categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list","id=my-store-1003");</script></div>

This is the most important Ecwid widget. It shows and includes a full-featured shopping cart with products, categories, catalog, checkout pages, etc.

To add an Ecwid store to the website, use the code example on the right. The 1003 is the ID of an Ecwid store. Make sure to specify your desired store ID in order to show your store!

Set main storefront URL for widgets

When you add store widgets, like search, minicart, categories menu, to a site page separate from the storefront widget, the storefront will open in a pop-up. This pop-up contains the whole store and works just fine. But in some cases it is more convenient to open the store on another website page instead of the pop-up.

You can do this with the help of the ecwid_ProductBrowserURL option.

'Tell’ Ecwid widgets that storefront is located at “http://www.example.com/store.html”

<script>var ecwid_ProductBrowserURL = "http://www.example.com/store.html";</script>

How Ecwid works by default

  • if a visitor uses the “minicart/vertical categories/search box” widget and a storefront is added on this page, all actions (go to cart, to category, etc.) will be made in that storefront widget
  • but if a storefront widget doesn’t exist on the same page page, a pop-up window with the storefront will be created on this page to complete the action

How Ecwid works with this option

When a merchant uses a storefront widget placed on another page of a website, you should use the ecwid_ProductBrowserURL option. If it’s set up, Ecwid works in such way:

  • if a visitor uses the “minicart/vertical categories/search box” widget and the storefront widget isn’t added on this page, they will be redirected to the URL speicified in the code and then the necessary actions will be performed there

For example, if a customer searches for a product on the page without a storefront, they will be redirected to a URL specified in ecwid_ProductBrowserURL variable and then Ecwid will show the search results on that page.

How to set up this option

In order to use it, you need to add the following JavaScript code to all pages, where Ecwid widgets are installed:

<script>var ecwid_ProductBrowserURL = "PB_URL";</script>

where PB_URL is the full URL of the page where your product browser widget (i.e. your Ecwid store) is installed.

For example:

<script>var ecwid_ProductBrowserURL = "http://www.example.com/store.html";</script>

Embed or remove storefront on demand

Dynamic embedding of Ecwid storefront widget

<div id="my-store-1003"></div>
<script>
window.ecwid_script_defer = true;
window.ecwid_dynamic_widgets = true;

   if (typeof Ecwid != 'undefined') Ecwid.destroy(); 
   window._xnext_initialization_scripts = [{
        widgetType: 'ProductBrowser',
        id: 'my-store-1003',
        arg: ["categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list"]
      }];

  if (!document.getElementById('ecwid-script')) {
      var script = document.createElement('script');
      script.charset = 'utf-8';
      script.type = 'text/javascript';
      script.src = 'https://app.ecwid.com/script.js?1003';
      script.id = 'ecwid-script'
      document.body.appendChild(script);
    } else {
      ecwid_onBodyDone();
    }
</script>

In some cases it is necessary to dynamically create and destroy Ecwid widget within the HTML page. This is useful for dynamic sitebuilders that switch to online store page without actually reloading page (e.g. making it visible).

You should use window.ecwid_dynamic_widgets variable to enable dynamic widget creating in Ecwid. See the example on the right that shows how to create and destroy Ecwid widget through the JavaScript functions.

Please note that this method allows to embed the storefront widget only. If you need to embed other widgets dynamically, please, use the code for deferred widget initialization

Delayed widget initialization

Delayed widget initialization

<div id="my-store-1003"></div>
<div id="productBrowser"></div>
<script>
  window.ecwid_script_defer = true;

  var script = document.createElement('script');
  script.charset = 'utf-8';
  script.type = 'text/javascript';
  script.src = 'https://app.ecwid.com/script.js?1003';

  document.getElementById('my-store-1003').appendChild(script);

  window._xnext_initialization_scripts = [
      { widgetType: 'ProductBrowser', id: 'productBrowser', arg: [
          '"categoriesPerRow=3","views=grid(4,4) list(10) table(20)","categoryView=grid","searchView=list","style=","responsive=yes","id=productBrowser"'
      ] }
  ];
</script>

Sometimes it is necessary to delay widget initialization while the website page finishes the initialization procedures. This is useful when the website is built dynamically using libraries such as ReactJs.

See the example of delayed initialization of Ecwid widget on the right.

Increase widget loading speed

DNS Prefetching of Ecwid’s resources

<link rel="dns-prefetch" href="//images-cdn.ecwid.com/">
<link rel="dns-prefetch" href="//images.ecwid.com/">
<link rel="dns-prefetch" href="//app.ecwid.com/">

To increase the loading speed of an Ecwid store, you can start loading Ecwid resources even before a customer opens the store page by the means of so-called prefetching (prerendering) browser feature. Not all browsers support this at this moment though.

Prefetching and prerendering of storefront page

<link rel="prefetch" href="http://www.example.com/store/"/>
<link rel="prerender" href="http://www.example.com/store/"/>

You can also add your storefront page to preload and prerender in the background for further increase in loading speed for browsers that have this feature.

Feel free to learn more about these techniques in https://css-tricks.com/prefetching-preloading-prebrowsing/

Add custom JavaScript code

Example of custom JavaScript to modify storefront

/*
 * Show a promo 'Free shipping' message on the cart page. 
 * In the example below, users will see a message on the cart page 
 * informing them that they will qualify for free shipping if their 
 * order is more than $99
 */

var promoMessage = "Orders $99 and up ship free!";
var minSubtotal = 99;
var widgets;

// Calculating subtotal and displaying the message
var checkSubtotal = function(order) {
  if (order) {
    var subtotal = order.total - order.shipping;
    if (subtotal > minSubtotal) {
      alert(promoMessage);
    }  
  }
}

// Detecting whether we're on the cart page and get the cart info
Ecwid.OnPageLoaded.add(function(page) {
  widgets = Ecwid.getInitializedWidgets();

  // if storefront widget is present on this page
  for (i = 0; i < widgets.length ; i++) {
    if (widgets[i] == "ProductBrowser") {
      if ('CART' == page.type) {
        Ecwid.Cart.calculateTotal(function(order) {
          checkSubtotal(order);
        });
      }
    }
  }
});

// Get color value for the message and store it in color variable
var color = Ecwid.getAppPublicConfig(appId);

// your code here
// ...

As soon as your script is loaded on the page with Ecwid storefront, you can access the page DOM and do pretty much everything you want by means of native JavaScript or whatever framework you want. If you use a JS framework, please make sure it’s already loaded on the page by the moment you start using it.

In addition, Ecwid provides a JavaScript API that you can use to retrieve store information and track Ecwid events on the page. For example:

  • Ecwid.getOwnerId() returns the store ID. You may want to use it to identify which store your script is loaded in now
  • Ecwid.OnPageLoad() and Ecwid.OnPageLoaded() help you to track store page switch and identify which page is opened
  • Ecwid.Cart object and its methods allow to manage the customer cart
  • EcwidApp.getAppPublicConfig will return store-specific data from application storage

More details: Ecwid JavaScript API

How to load custom JavaScript anytime storefront is loaded

Ecwid API allows you to do the same in more convenient way: you simply specify the URL of file with your custom JavaScript code and Ecwid automatically loads that code in the user storefront. So you don’t need to put the JS on merchant site manually or ask them to do that.

In more details:

  1. After your app is registered, contact us and provide the https URL of the .css and/or .js file you’d like to load in the user storefront.
  2. When asking a user to install your app, Ecwid will request the customize_storefront permission from them. (If your app is for a specific store, make sure to add customize_storefront scope in the OAuth process.)
  3. The next time the user storefront is loaded in any browser or website, the specified external JS/CSS files will be automatically appended, loaded, and executed on that page.

Q: How to know what Ecwid widgets are on a page?

If your applcation customizes storefront, your script will be loaded at all times when app.ecwid.com/script.js?{store_id} is on a page. It means that if a simple search widget is present on a page, your script will be executed.

Ecwid widgets can be also embedded in many ways:

  • as a part of a website page
  • in an iframe
  • certain widgets are displayed only (like search and minicart, no storefront)

So, it is important to know where exactly your application is loaded: if there is a storefront present on a page or if it’s just a search widget. To check that, use Ecwid.getInitializedWidgets() function of Ecwid Javascript API. Using it, you can determine whether your app functionality needs to be initialized or not.

Q: What is the best way to add new scripts from my code?

Add external script to the page example

var s = document.createElement("script");
s.type = "text/javascript";
s.src = "https://example.com/example.js";
document.head.appendChild(s);

In case if you need more than one JavaScript code executed on a page, you can load additional scripts from within your base app JavaScript code.

We recommend that you load external JS files using a standard function createElement(). See example code on the right. It allows you to create a new <script> element on a page with the parameters you need and then append it to the DOM tree to get loaded and executed.

More details about this approach: W3CSchools

Access merchant in-app preferences

Applications can work and look differently in various stores, so you can provide tailored user experience to the store owner and a website they have in your application.

App public config allows apps to access user specific data in storefront as soon as it starts to load, so no calls to external servers are required and result is available right away. It’s recommended that you use app storage to access public user data in storefront area of your application.

How it works:

  1. App saves public data in public storage in backend
  2. App gets public data from public storage in storefront
  3. App tailors user experience to merchant settings

For example, using this method you can pass store ID to a storefront, category or product ID where the changes need to apply or whether your widget needs to be shown in storefront.

To find out more about this process, please check Public App Config section.

Store-specific custom JavaScript

Example of the script that dynamically loads store-specific code

// Load external script with store
function loadConfig(ecwidStoreId, callback) {
  var script = document.createElement("script");
  script.setAttribute("src", '//example.com/myapp/store' + ecwidStoreId + '.js');
  script.charset = "utf-8";
  script.setAttribute("type", "text/javascript");
  script.onreadystatechange = script.onload = callback;
  document.body.appendChild(script);
}

// Application functionality
function doCoolStuff() {
  //...
}

// Get color value for the message and store it in color variable
var color = Ecwid.getAppPublicConfig(appId);

// Get Ecwid store ID and start working
loadConfig(Ecwid.getOwnerId(), doCoolStuff);

In most cases, your application behavior will vary depending on the store it is opened in. Although Ecwid API allows you to specify only one JS file per application, your application can detect the current Ecwid store ID and act correspondingly. Use the Ecwid.getOwnerId() method to detect the user store ID in your script.

For example, let’s say you need to dynamically add a store-specific configuration to your script when it’s executed in some particular storefront. You can detect the store ID in your script and call a script on your server containing the store-specific code.

To get information for that specific store you can use Ecwid.getAppPublicConfig function in Ecwid Javascript API. See more details on how to access that data in Application data section of documentation.

Caching JavaScript file contents

When your external JS file is loaded on a page, it is loaded like any other resource via a GET request by a web browser. If you’d like to use caching to increase the loading speeds of your script, we can suggest several options:

  • invalidate cache for your JS file link when deploying a new version
  • in your JS file, place a code that will get the latest JS assets file from your server dynamically and append it to a page (instead of the using an actual code of your app on that URL)
  • don’t use caching, so that your files for storefront are always up-to-date for any user

Using jQuery on store pages

Checking for jQuery on a page example

// function to load jQuery

function loadjQuery(){
  var jq = document.createElement('script'); jq.type = 'text/javascript';
  jq.src = 'https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.2.js';
  document.getElementsByTagName('head')[0].appendChild(jq);
}

if (typeof jQuery == 'undefined') {  
  loadjQuery();
} else {}

// your app code
// ...

jQuery is a very popular JavaScript library that is used in many websites. The developers of themes for Wordpress CMS, for example, include this library right into the theme to have access to its functions and to operate various HTML elements on the page easily.

Ecwid storefronts can be customized in many ways, for example: you can set specific behaviour for each page or each user that visits those pages. Some developers prefer using native JavaScript functions to change the position or the display of certain elements. But many use different versions of popular jQuery library.

To ensure that your jQuery version code doesn’t conflict with other applications that change Ecwid storefront, please see our guidelines:

For simple modifications

When your modifications don’t require specific versions of jQuery loaded on a page and are fairly simple, we suggest you follow this algorithm:

First, check for jQuery object on current page. If no object is defined, load any jQuery version you prefer using the example code on the right. If there is already jQuery object available - skip the loading and use the curreny jQuery on this page.

For complex modifications

When you are using advanced jQuery’s features such as jQuery UI, version specific functions, etc. it will be hard to work with, if a website already has varuous jQuery versions on a page. To avoid any version conflicts with current page jQuery version, we suggest you use jQuery noconflict feature. Check out how it works: https://api.jquery.com/jquery.noconflict/

Custom URL redirect after an online purchase

Setting custom URL redirect after online purchase

<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.custom_redirect_after_purchase = 'YOUR CUSTOM URL HERE';
</script>
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.custom_redirect_after_purchase = 'https://mycoolstore.com/thank-you.html';
</script>

Some merchants may want to send their customers after a successful online purchase to a custom URL. Using the configuration on the right you can set the URL where the customer should be redirected.

Important: the redirect will work only for online payment methods. For offline payment methods, consider using the Custom URL for 'Thank you’ page application.

Generate cart with products

Ecwid JavaScript API allows you to add items to customer’s cart automatically. This can be useful when you are using custom storefront to provide any type of button to add products to cart.

Using the following steps you will be able to create links to your storefront with products in cart for your customers. So all they have to do is just clikc that promo link to go to your store and have products added to cart automatically.

Let’s check out how this can be achieved:

Step 1: Add external files to your website

Script and CSS to load on your storefront page

<link rel="stylesheet" type="text/css" href="https://s3.amazonaws.com/ecwid-addons/apps/ecwid-cart-app/cartapp.css">
<script src="https://s3.amazonaws.com/ecwid-addons/apps/ecwid-cart-app/cart.js"></script>

Add this code to the source code of the page, where your Ecwid storefront is displayed. Add the script after or below Ecwid integration code.

Step 2: Generate your cart

Generate items in cart example

var cartItems = [{
    "id": 66821181, // ID of the product in Ecwid
    "quantity": 3, // Quantity of products to add
    "options": { // Specify product options
        "Color": "White",
        "Size":"11oz"
    }
}, {
    "id": 66722581,
    "quantity": 5
}];

var cart = {
     "gotoCheckout": true, // go to next checkout step right away (after 'Cart' page)
     "products": cartItems, // products to add to cart
     "profile": {
         "address": { // Shipping address details
             "name": "john smith",
             "companyName": "general motors",
             "street": "5th Ave",
             "city": "New York",
             "countryCode": "US",
             "postalCode": "10002",
             "stateOrProvinceCode": "NY",
             "phone": "+1 234 235 22 12"
         },
         "billingAddress": { // Billing address details
             "countryCode": "US",
             "stateOrProvinceCode": "AL",
         },
         "email": "test@test.com", // Customer email
         "orderComments": "Comments!" // Order comments
     }
 }

cart = JSON.stringify(cart);
cart = encodeURIComponent(cart);

console.log(cart);

// prints the resulting string you need to use in step 3
//
// %7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D
//

In order for the script to add items to cart, we need to 'tell’ it what items to add. Check the example on the right on how to do this. The cart variable will have the generated cart content in it.

The syntax is very similar to adding products to cart via Ecwid JavaScript API.

Step 3: Create a link for customers

Final link structure

http://example.com/store#!/~/cart/create={generatedCartCode}

Final link to generated cart example

https://www.ecwid.com/demo#!/~/cart/create=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D

Now we need to fill in customer’s cart when your custom link is opened.

First things first, let’s determine where your Ecwid store is displayed and get a direct link to that page. For example, our demo store is located in: https://www.ecwid.com/demo And to fill in customer’s cart with items that you seleted earlier, we need to create a link to your storefront with the generated cart part.

Example link

Generated link with products added automatically to cart for Ecwid demo store will be:

https://www.ecwid.com/demo#!/~/cart/create=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%22%2C%22postalCode%22%3A%2210002%22%2C%22stateOrProvinceCode%22%3A%22NY%22%2C%22phone%22%3A%22%2B1%20234%20235%2022%2012%22%7D%2C%22billingAddress%22%3A%7B%22countryCode%22%3A%22US%22%2C%22stateOrProvinceCode%22%3A%22AL%22%7D%2C%22email%22%3A%22test%40test.com%22%2C%22orderComments%22%3A%22Comments!%22%7D%7D

Storefront JavaScript API

Any Ecwid storefront has a JavaScript API available at all times to help users create various customizations for their storefronts.

Its features include:

  • detect currently opened page details
  • set shipping and billing address for customer
  • get customer’s cart details
  • manage customer’s cart and others.

To find our more about it, plesae see the Storefront JavsScript API Documentation.