NAV

Ecwid Javascript SDK

<!-- Include Ecwid JS SDK -->
<script src="https://djqizrxa6f10j.cloudfront.net/ecwid-sdk/js/1.2.3/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.3/ecwid-app.js .

init

Example of using EcwidApp.init() method

...
// Initialize the application
EcwidApp.init({
  app_id: "my-super-app", // use your application namespace
  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). This is not the same as clientId.
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 embedded 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: in a POPUP or in a PAGE. PAGE is a default mode when app is displayed in a separate tab in Ecwid Control Panel

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

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.

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.

setAppPublicConfig

Save a string to 'public’ key in application storage

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

EcwidApp.setAppPublicConfig(data, callback);

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

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.

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.