Ecwid JS SDK

Ecwid Javascript SDK is a set of basic JS functions for interacting with Ecwid from within your Native application.

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

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

init

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

The app_id value is a client_id of your application. Get it on the #develop-apps page of your dev store.

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

Parameters

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

NameTypeDescription
app_idstringclient_id 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.

openPage

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 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
The part you need: products
The method call: EcwidApp.openPage('products');

  1. Open specific order details page

Target URL: https://my.ecwid.com/store/5035009#order:id=938&return=orders
The part you need: order:id=938&return=orders
The result: EcwidApp.openPage('order:id=938&return=orders');

ready

You can use the EcwidApp.ready() method in your application to inform Ecwid of the 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.

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

// Show app UI
EcwidApp.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

sendUserToUpgrade

EcwidApp.sendUserToUpgrade(features);

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

getAppClientId

EcwidApp.getAppClientId();

The method returns the appId the EcwidApp object was initialized with.

📘

Methods listed below are now deprecated. However, their functionalities are still available thorugh the REST API.

getApiDomain [Deprecated]

EcwidApp.getApiDomain();

The method returns the API domain (https://app.ecwid.com/api/v3/) useful to construct a URL for API endpoints and during authorization via a redirect from the iframe.

var url = window.EcwidApp.getApiDomain() + window.EcwidApp.getPayload().store_id + '/profile';
  var request = {
    'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + window.EcwidApp.getPayload().access_token,
    },
  };

fetch(url, request)
  .then((response) => {
    if (!response.ok) {
      throw new Error('HTTP error! Status: ' + response.status);
    }
    return response.json();
  });

getPayload [Deprecated]

EcwidApp.getPayload()

This is an outadet method for accessing Ecwid API right from Ecwid Control Panel without server-side decryption. It's still used in some old applications. All new applications use more secure server-side auth (see Authentication in native apps section). If your app still uses getPayload()method, please contact us at [email protected], so we can update your app and help you woth transitioning to the server-side auth.

Find an example of EcwidApp.getPayload() use below:

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

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

📘

Fields marked in bold are always sent in the payload. Others are sent depending on conditions.

setAppStorage [Deprecated]

Add new data to the Application Storage for your app. More on the Application 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 Application storage
callbackFunctionSpecify your callback function if needed

Your object data is stored as corresponding keys in the Application storage in 'key' : 'value' format. This method accepts only string type values in your data object, so make sure even the numerical values of your object are of string type.

getAppStorage [Deprecated]

Receive data saved in Application storage for your app.

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

Parameters

EcwidApp.getAppStorage accepts two parameters:

NameTypeDescription
keystringSpecify the key that you need to get value from. If no key is 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

getAppPublicConfig [Deprecated]

EcwidApp.getAppPublicConfig(callback);

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

Parameters

EcwidApp.getAppPublicConfig accepts one parameter:

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 application config

setAppPublicConfig [Deprecated]

Public config allows you to interact with some parts of the data saved in Application storage on the storefront. The remaining data will still be private.

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

EcwidApp.setAppPublicConfig(data, callback);
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. Public application config

🚧

Data that you save for public access cannot exceed 256Kb

Data saved to the public config can be accessed on the storefront with the Ecwid Javascript API.

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

📘

This method accepts string type values only in your data object.

closeAppPopup [Deprecated]

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. When application is opened in a tab mode, nothing will happen.