Public application config

Application Storage allows to save public app config and access it easily in a storefront later. Public config is aways stored in a public key of your application storage.

Use case example

You may plan to build an app that displays custom text on a cart page written by store owner. Or you want to create a fully customizable widget, where merchant can input custom text, change its size, color, background and do other customizations.

Ecwid.getAppPublicConfig('my-cool-app');
// "enabled"

To do all of the above, your app will need to:

  1. Request all these fields from a merchant in your app interface
  2. Save them to the public config
  3. Apply them in storefront pages

You may also want to store multiple values in a public app config. See information on these steps in details below.

Save public data

There are two ways to save user’s data to app public config:

  1. For native client-side applications, created in Javascript, use setAppPublicConfig() function of the Ecwid Javascript SDK
  2. For external or server-side applications, use REST API for saving user data to public key of application storage
var categoryId = '12345';

EcwidApp.setAppPublicConfig(categoryId, function(){
  console.log('Public config saved!');
});
POST /api/v3/1003/storage/public HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Authorization: Bearer e***s0
Cache-Control: no-cache

'12345'

📘

Check out examples on saving and getting multiple fields in public app config: examples

Important:

  • App public config can accept any string with the size less than 256Kb. Please make sure to store the required data only.
  • App public config can be accessed by any 3rd party in storefront, if they know your appId.

🚧

If any other 3rd party obtains your appId, they will have access to public user data of your application in storefront. Make sure not to store any user sensitive data in app public config.

Get public data

Ecwid.OnPageLoaded.add(function(page){
  // Get public config in storefront
  // 'my-cool-app' is your appId value
  var category_id = Ecwid.getAppPublicConfig('my-cool-app'); 

  category_id = parseInt(category_id);

  if (page.categoryId == category_id) {
    // initialize your app
  } else {
    return;
  }
});
// variable to store our public config
var publicConfig;

// get app public config in native app
EcwidApp.getAppPublicConfig(function(value){
  console.log(value);
  // '{ "color" : "red", "page_id" : "123456" }'

  publicConfig = value;
  // parse the string to a JS object
  publicConfig = JSON.parse(publicConfig);
  console.log(publicConfig.color);
  // 'red'
});

If your app customizes Ecwid storefront, you can get public config of your app using Ecwid JS API. In your Javascript file, which is executed when a storefront is loaded, you should get config using this API call: Ecwid.getAppPublicConfig('appId'). It will return a string value that you saved previously.

To get the value, specify your appId (app client_id) as its parameter and store the result of this function in a variable. If you are not sure on what your appId is, contact us. App public config is available to your app as soon as storefront starts to load.

Access single or multiple values

Access a single public value

Use EcwidApp.setAppPublicConfig to save a simple string to use in storefront. For example, you can store the status of your widget (enabled / disabled) based on user preferences in native applications and then access it in storefront using Ecwid.getAppPublicConfig.

// Check whether widget needs to be shown
var widget_enabled = 'true';

EcwidApp.setAppPublicConfig(widget_enabled, function(){
  console.log('Public app config saved!');
});
Ecwid.OnPageLoaded.add(function(page){
  var widget_enabled = Ecwid.getAppPublicConfig('ecwid-example-app');

  if (widget_enabled == 'true') {
    // initialize your app
  } else {
    return;
  }
});

Access multiple public user data

Sometimes applications require more user information in storefront and it's possible to access it as well as a simple value. To save more than one value and utilize it as a key : value storage within app public config, you can save your data in a JSON format in a single string using EcwidApp.setAppPublicConfig.

After that, you can access this data in storefront using Ecwid.getAppPublicConfig. Then parse it via standard JavaScript function JSON.parse(), which will present your data in a JavaScript object. Check out example on the right to find out how it works.

🚧

App public config can accept any string with the size less than 256Kb. Make sure to store the required data only.

Example

//
// Save multiple public user data in native client-side app using JavaScript SDK
//

var data = '{ "color" : "red", "page_id" : "123456", "text" : "Get 10% off on checkout with this code: ABCDEFG" }';

EcwidApp.setAppPublicConfig(data, function(){
  console.log('Public app config saved!');
});
Ecwid.OnPageLoaded.add(function(page){
  var data = Ecwid.getAppPublicConfig('my-cool-app');
  data = JSON.parse(data);

  var color = data.color;
  var page_id = data.page_id;
  var text = data.text;
  var added;

  page_id = parseInt(page_id);

  if (page.categoryId == page_id && added !== true) {
    div = document.getElementsByClassName("ecwid-productBrowser")[0];
    div.innerHTML = text + div.innerHTML;
    
    // customize text style using color 
    // ...

    added = true;
  }
  else {
    return;
  }
});