Create a Public AppCustomize Your Store
Chat on SlackContact Us

Add custom JavaScript

You can access the Ecwid storefront DOM and do pretty much everything you want by means of native JavaScript or whatever framework you want. In addition, Ecwid provides a JS API that you can use to retrieve store information and track Ecwid events on the page. If you use a JS framework, please make sure it's already loaded on the page by the moment you start using it.

📘

Permission required: customize_storefront (see Access scopes)

How to load custom JavaScript anytime storefront is loaded

Ecwid can load and execute a JS file from your server when store loads on page automatically.

Requirements

  • A registered app with customize_storefront access scope
  • Ready or dummy JS file uploaded to your server
  • Ecwid store on a paid plan

Set up

  1. After your app is registered, contact us and provide HTTPS URL of .js and/or .css file you’d like to load in the user storefront.
  2. Install your app into the target Ecwid store using instructions provided in registration email.
  3. The next time storefront is loaded in any browser or website, your JS/CSS files will be automatically appended, loaded, and executed on that page.

Custom JavaScript FAQ

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

If your application 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 even if a simple search widget is present on a page, your script will be executed too.

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?

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(). 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.

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);

More details about this approach: W3CSchools

🚧

Avoid using the document.write() function as it works synchronously and will slow down the page load.

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.

In-app preferences workflow

  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, check Public application config section.

Store-specific custom JavaScript

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 Storefront JS API). See more details on how to access that data in Application storage section of documentation.

// 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);

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

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.

// 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
// ...

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

jQuery 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.

jQuery 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/

📘

We recommend loading your jQuery from Google's CDN to ensure it is available at all times.