Building a native app

Set up your application

After the app registration you will need to provide us with additional details about your app interface in the Ecwid Control Panel. These details are necessary to properly show your page, please see the required details below:

Parameter	Meaning
Iframe URL	This is a HTTPS URL of the application page hosted on your server, which will be loaded in Ecwid Control panel. Requirements: It must load over HTTPS The page must not contain header/footer, i.e. you will need to design this page as an embeddable, not as a standalone application. The page must be mobile-ready for cases when store owners go to Ecwid Control Panel on mobile devices. The page content should not contain the word 'Ecwid', so we can offer your app to our partners Its interface must use Ecwid CSS Framework The page must initialize the app using Ecwid Javascript SDK to be displayed
App page title	This will be the title of the tab in Ecwid control panel where your application resides. Please keep it short as it will reside in a row of native Ecwid tabs and other applications
Control panel section	The section of Ecwid control panel where you want your application to be added. Supported sections: Sales – choose this if your application works with orders or customers Catalog – choose this if your application works with products, variations, product images etc. Marketing – this section is for the applications working with discounts, coupons, loyalty programs and other promotion features Settings – you can choose this section if you need to place your application settings at the same level as the store settings Reports - choose this section if your app shows store statistics Sales Channels - choose this section if your app adds another sales channel for a store Design - choose this section if your app changes store design: colors, buttons, order of storefront elements, etc. Payment and Shipping pages - one of this sections is assigned if you develop a payment or shipping integration

📘
Access scope required: add_to_cp

If you already have a registered app and want to make it native, you can contact us to adjust your app settings.

App page template

📘
Native app source code example: https://github.com/Ecwid/sample-native-app

<!doctype html>
<html>

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

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

    // Get the store ID and access token
    var storeData = EcwidApp.getPayload();
    var storeId = storeData.store_id;
    var accessToken = storeData.access_token;
    var language = storeData.lang;

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

    // do something...
  </script>

  <!-- Include Ecwid CSS Framework -->
  <link rel="stylesheet" href="https://d35z3p2poghz10.cloudfront.net/ecwid-sdk/css/1.3.19/ecwid-app-ui.css"/>  
</head>

<body class='normalized'>
  <div>Show something</div>

<!-- JS for CSS Framework components -->
  <script src="https://d35z3p2poghz10.cloudfront.net/ecwid-sdk/css/1.3.19/ecwid-app-ui.min.js">
  </script>
</body>

</html>

Notes on app template

The EcwidApp.init() method initializes the application within Ecwid Control panel and allows it to show the page content
The EcwidApp.getPayload() method allows you to get the Store ID and REST API access token. See details in the further sections
Ecwid will load your app's Iframe URL with a payload to help identify the merchant's store. To find out more about the store authentication process in the app tab, see the Authentication section.
See the detailed description of the init() and getPayload() functions here: Ecwid JS SDK.

A sample native application with examples of how to access Ecwid REST API, save data to application storage and how to design the app is available here: https://github.com/Ecwid/sample-native-app

📘
If your app for public use, it is required to use Sample Native App interface for its user interface.

Native apps FAQ

Q: What is my app_id?

When user opens the application tab, the browser's address bar URL will have a format like this:

https://my.ecwid.com/cp/#app:name=my-cool-app&parent-menu=sales&app_state=orderId%3A%2012

Where the my-cool-app is your app_id which you will need to use in this code template to initiate the application on the page. The sales part is the Ecwid Control Panel section where the app is embedded into.

Q: Do I need to use Ecwid styles for my app?

Native apps become a part of an Ecwid Control Panel, hence they need to look like a part of it. You can use Ecwid CSS Framework to achieve it in your app. Ecwid CSS Framework allows you to create interface faster and easier. If your application is a custom solution for your own store, we still recommend using the Ecwid styles, but it's not mandatory.

Native interface translations

You are able to translate native application interface based on the language of Ecwid Control Panel. The current language of Ecwid Control Panel is provided in the authentication payload your application receives. Authentication payload can be sent in two modes:

client-side (via hash #)
server-side (URL query string: ? and &)

How to translate your Native app

Find out how your app gets the payload (check your app iframe URL in browser's dev tools)
Get lang field value from the payload
Load the interface based on that value

If the current language is not supported, use the fallback labels. For example, load English texts if user is Spanish and you don't have Spanish translations yet.

More info on getting and parsing authentication payload: Authentication in native apps