Customizing Ecwid Storefront

The Ecwid API allows you to access store details using REST endpoints. What makes it even more powerful is the ability to load custom JavaScript and CSS files to alter the look and behavior of the store, providing extended and custom features for it in a way that these extensions look and feel like native Ecwid features. Below you can find guidelines on how to create the best app that customizes the storefront.

Features

When a user installs an application, the app must require them to ask for the customize_storefront access scope. If the application has custom JS or CSS links specified, Ecwid will load those files alongside the script on a website. The Ecwid script is any instance of loading the “https://app.ecwid.com/script.js{storeID}” on a page.

To help integrate even more deeply with the storefront, use the Ecwid JavaScript API and any other means that you have for providing the necessary functionality, like a jQuery library. More details about customizing the storefront can be found in the Ecwid API Documentation.

Workflow

Some basic steps of your app workflow should include:

  • Check if enabled
    If the application is changing the storefront in some significant way (adds new functionality, changes the design, etc.), it is important to have an on/off switch somewhere in the application settings. This will help you and your app users to debug any issues that may arise without having to reinstall the application
  • Check for widgets
    The Ecwid Javascript API allows you to check whether your app needs to execute on this particular web page by checking the Ecwid widgets present on it. Use the Ecwid.getInitializedWidgets function to check widgets loaded on a page.
  • Check for jQuery
    Your application can change the position or hide some elements on specific pages in Ecwid. Some developers prefer jQuery for a more simple process. However, if there are many apps that use jQuery, they all should check if it’s loaded before loading one themselves. Use the code from this section to get you started.
  • Launch app code
    Now that you’ve ensured that everything looks good and is ready for your app, start generating the code for your storefront customizations.

Recommended:
If your application needs to receive some user-specific data in the storefront, like color, text size settings or other information, use public application config to pass values to the storefront from your application’s tab in the Ecwid Control Panel (for native apps) or use the “public” key of Ecwid App Storage (for external apps).

Full native application also working in storefront (Custom URL for “Thank you” page app from the Ecwid App Market) source code example is available here: https://github.com/Ecwid/custom-thank-you-page-app

Requirements

While some steps of the recommended workflow can be skipped depending on the nature of the application, the below requirements are applicable for all applications in the Ecwid App Market:

  • Provide enable/disable
    Applications that change the storefront are also working in all the different environments as Ecwid stores. Sometimes the app can work perfectly in one website, but not work in another. To provide a quick way for a merchant to disable the app and inform you about it, you should include enable/disable functionality for your application.
  • Avoid unexpected changes to the storefront
    Let’s say that your app adds a custom note in the storefront to inform customers of a sale, opening hours, etc. This is a simple addition, but it can easily change the look of the store or website. For example, it may change the website background or mark all inputs disabled on a page. When developing an app, make sure that it doesn’t change any basic styles of the page, so it only applies to the app area.
  • Test in multiple browsers
    Your app should work effectively and consistently in all major web browsers. Please run the necessary QA tests with various browsers and settings before submitting your app for review.
  • Fast load of content
    When user has many applications that change the storefront, it influences the loading speed of the storefront itself, due to having multiple HTTP requests running simultaneously. Ecwid users and their customers are spread throughout the whole world, so please make sure your app files are optimized for efficient loading.

Recommended:
We recommend designing your app as close to the look and feel of Ecwid as possible. This way you will provide a smooth, consistent experience for the customers of a store and it’s more likely that the store owners will continue using your application. You can check the basics of our design elements in the Ecwid CSS Framework documentation.

Related links