NAV

Ecwid Javascript SDK

<!-- Include Ecwid JS SDK -->
<script src="https://djqizrxa6f10j.cloudfront.net/ecwid-sdk/js/1.2.5/ecwid-app.js"></script>

Ecwid Javascript SDK is a simple JS framework with a set of basic JS functions that will help you to embed your app to Ecwid Control Panel and interact with Ecwid from within your application.

To use the SDK, include this file into your app: https://djqizrxa6f10j.cloudfront.net/ecwid-sdk/js/1.2.5/ecwid-app.js .

init

Example of using EcwidApp.init() method

// Initialize the application
EcwidApp.init({
  app_id: "my-super-app", // use your application client_id
  autoloadedflag: true, 
  autoheight: true
});

The EcwidApp.init() method initializes your app inside Ecwid Control Panel. Call it once at the beginning of executable code in your app.

You can get the app_id using the URL in your browser when you open your application tab. Here’s a typical link that you can get when you open your app: https://my.ecwid.com/cp/CP.html#app:name=my-super-app&parent-menu=promotions

The app_id here is the my-super-app part. Make sure to use this to initialize your application with Ecwid JS SDK.

Parameters

The only parameter is a JS object with the following fields:

NameTypeDescription
app_idstringNamespace of your application (as set in the application settings)
autoloadedflagbooleanDefine how Ecwid should detect when your app is loaded. Set as true, if you want Ecwid to automatically detect the fact that you your app is loaded. Ecwid uses the window.onload event of your application document. If you want to contol when Ecwid should start displaying your app and inform it of your app’s ready state, you should set this flag as false and use the EcwidApp.ready() method. As soon as the app is loaded, Ecwid hides the 'Loading’ animation and shows the app content.
autoheightbooleanSet as true if you want Ecwid to dynamically adjust your app iframe height depending on your app content. If you want to control the iframe size yourself, set this flag as false and use the EcwidApp.setSize() method.

getPayload

Retrieving store ID and access token using Ecwid JavaScript SDK

    var storeData = EcwidApp.getPayload();
    var storeId = storeData.store_id;
    var accessToken = storeData.access_token;
    var language = storeData.lang;
    var viewMode = storeData.view_mode;

    if (storeData.public_token !== undefined){
      var publicToken = storeData.public_token;
    }

    if (storeData.app_state !== undefined){
      var appState = storeData.app_state;
    }

    // now you know the user you interact with and can access Ecwid API on their behalf

EcwidApp.getPayload()

Above, we explained how your app can be a client-side HTML/JS application and still access Ecwid API right from Ecwid Control Panel (see Authentication in native apps section). There, we used the EcwidApp.getPayload() method to get the store ID and API access token.

The payload is a JSON with the following fields:

NameTypeDescription
store_idnumberEcwid store ID
langstringUser language (which is currently set in their Control Panel). Use this parameter to translate your application UI to the user language.
access_tokenstringSecure oAuth token
app_statestringURL Encoded application state
public_tokenstringPublic oAuth token for Ecwid REST API
view_modestringMode used to display the application interface: POPUP, PAGE or INLINE. PAGE is a default mode when app is displayed in a separate tab in Ecwid Control Panel, POPUP is used when the app UI is displayed in a popup on any page of Ecwid CP, INLINE type is used for displaying the interface inside an element on a page where other elements are also present

openPage

Open some page inside Control Panel from your application

EcwidApp.openPage('products');

The EcwidApp.openPage() method allows you to direct the user to some particular page in the Control Panel

To open a page in Ecwid CP, you will need to get its identification after the hash (#) part in the URL.

Parameters

NameTypeDescription
pagestringHash part of of the page URL in the Control Panel. Examples: billing will open the Billing page, products will open the Catalog page.

Examples:

1) Open Catalog page

Target URL: https://my.ecwid.com/store/1003#products What we need use: products

The result: EcwidApp.openPage('products');

2) Open specific order details page

Target URL: https://my.ecwid.com/store/5035009#order:id=938&return=orders What we need to use: order:id=938&return=orders

The result: EcwidApp.openPage('order:id=938&return=orders');

ready

Show app UI when your app is ready to show it

// Initialize the application
EcwidApp.init({
  app_id: "my-super-app", // use your application client_id
  autoloadedflag: false, 
  autoheight: true
});

// Show app UI
EcwidApp.ready();

You can use the EcwidApp.ready() method in your application to inform Ecwid of ready state of your application.

For example, you may need to make a few API calls or load some additional assets before your app UI should be displayed to the user. In this way, pass false in the autoloadedflag parameter in the EcwidApp.init() method and call the .ready() function when you are ready.

setSize

Set your app iframe size from within the app

EcwidApp.setSize({height: 800});

We recommend using the autoheight parameter set as true in EcwidApp.init() function to let Ecwid dynamically adjust your app iframe size depending on your application content size. But if you want to control the iframe size yourself, set that flag as false and use this EcwidApp.setSize() method.

Parameters

The only parameter is a JSON object with the height field:

NameTypeDescription
heightnumberThe iframe height in pixels

setAppStorage

Save multiple 'key’ : 'value’ data to app storage

var data = { 
  color : 'red',
  size : 'big',
  page_id : '123456'
};

EcwidApp.setAppStorage(data, callback);

Parameters

EcwidApp.setAppStorage accepts two parameters:

NameTypeDescription
dataObjectPlace object you want to add in storage
callbackFunctionSpecify your callback function if needed

Your object data as specified in example will be stored as corresponding keys in your application storage in 'key' : 'value' format.

This method accepts only string type values in your data object, so make sure all values in your object, such as 'red’, are of type string.

Learn more about application storage: https://developers.ecwid.com/api-documentation/application-storage

setAppPublicConfig

Save a string to 'public’ key in application storage

var data = '{ "color" : "red", "page_id" : "123456" }';

EcwidApp.setAppPublicConfig(data, callback);

Get app public config in your native app

var publicConfig;

EcwidApp.getAppStorage('public', function(value){
  console.log(value);
  // '{ "color" : "red", "page_id" : "123456" }'

  publicConfig = value;
})

publicConfig = JSON.parse(publicConfig);

console.log(publicConfig.color);
// 'red'

Parameters

EcwidApp.setAppPublicConfig accepts two parameters:

NameTypeDescription
dataStringPlace json string you want to add in public storage
callbackFunctionSpecify your callback function if needed

The string that you provide in data variable will be specified for public key in application storage. Learn more

You will be able to retrieve it using Ecwid Javascript API in storefront.

If you need to pass more than one value, you can specify your data in a json string and parse that string in Ecwid storefront.

getAppStorage

Get all data from application storage

EcwidApp.getAppStorage(callback);

Example

EcwidApp.getAppStorage(function(allKeys) {
  // returns an array of objects, containing all keys and their values in your app storage
  console.log(allKeys);
});

Get data from application storage by key

EcwidApp.getAppStorage(key, callback);

Example

EcwidApp.getAppStorage('color', function(value){
  //prints 'red' 
  console.log(value);
});

Parameters

EcwidApp.getAppStorage accepts two parameters:

NameTypeDescription
keystringSpecify key that you need to get value from. If no key specified, all data will be returned
callbackFunctionSpecify your callback function

Using this method you can retrieve either all keys and their values that are located in your application storage or get the value of a specific key.

Learn more about application storage: https://developers.ecwid.com/api-documentation/application-storage

getAppPublicConfig

Get app public config value function usage

EcwidApp.getAppPublicConfig(callback);

Get app public config value example

EcwidApp.getAppPublicConfig(function(publicData) {
  // returns value of 'public' key in application storage
  console.log(publicData);
});

Parameters

EcwidApp.getAppPublicConfig accepts two parameters:

NameTypeDescription
callbackFunctionSpecify your callback function

Using this method you can retrieve the value of public application config stored in your application storage. Learn more about public app config: https://developers.ecwid.com/api-documentation/public-application-config

closeAppPopup

EcwidApp.closeAppPopup();

When a native application is opened in a popup window in Ecwid Control Panel, executing this function will close that popup for the user.

In case when application is opened in a tab, nothing will happen.

sendUserToUpgrade

Send user to upgrade usage

EcwidApp.sendUserToUpgrade(features);

Send user to upgrade examples

// Send user to upgrade to get Product Variations feature
EcwidApp.sendUserToUpgrade(["COMBINATIONS"]);

// Send user to upgrade to the minimal plan where Order Editor and Marketplaces features are available
EcwidApp.sendUserToUpgrade(["ORDER_EDITOR", "MARKETPLACES"]);

Ecwid JS SDK allows your app interface to initiate the upgrade process for a user. The upgrade process is launched using the EcwidApp.sendUserToUpgrade() function, where you should provide the feature to upgrade to.

When you pass features array as argument, Ecwid will determine the minimum required plan for merchant to use them and initiate upgrade process

Features list is available in the Store profile endpoint of Ecwid REST API. Contact Ecwid team to find out the feature name if it’s missing in your store.