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 show your page properly, please see the required details below:

ParameterMeaning
Iframe URLThis 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 mention words 'Ecwid' or 'Lightspeed', 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 titleThis 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 sectionThe 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>
	<!-- Add values from the decrypted payload and initialize the app -->
  <script>
    // Initialize the application
    EcwidApp.init({
      app_id: "my-super-app", // client_id of your application
      autoloadedflag: true, 
      autoheight: true
    });

    // Get store ID, language, and access token from decrypted payload JSON
    var payload = <?php echo $result; ?>;
    var storeId = payload.store_id;
    var secret_token = payload.access_token;
    var language = payload.lang;

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

    // load additional scripts, styles if necessary...
  </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 is required. It initializes the application within the Ecwid Control panel and allows it to show the page content. See the detailed description of the init() function here: Ecwid JS SDK.
  • Ecwid will load your app's iframeUrl with an encrypted 'payload' query parameter. Decrypt it to identify the merchant's store and get its REST API access. Find decryption examples in the Authentication section. Decrypted JSON is saved as a '$result' variable there.
  • If your app URL doesn't have the 'payload' parameter, please contact us at [email protected], so we can update your app. Most likely it uses our old deprecated authentification method.

Here's a Sample Native App with examples of design and methods to access Ecwid REST API or save data to application storage: https://github.com/Ecwid/sample-native-app

📘

Please note, that the "payload" section of the Sample Native App is now deprecated! Use methods described in Authentication section instead

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.

You can also get your app's client_id on its settings page on the #develop-apps page.

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

Public Native applications become a part of an Ecwid Control Panel, hence they must look like a part of it. Using our CSS Framework is a requirement for public applications. Ecwid CSS Framework also has many ready-to-use elements and blocks allowing you to create an interface faster and easier.

If your application is a custom solution for your own store, we still recommend using the styleguide, but it's not mandatory.

Native interface translations

Translate Native application interface based on the language of Ecwid Control Panel. Current language of the Control Panel is provided in the 'payload' your application receives: Authentication payload

How to translate your Native app

  1. Get lang field value from the payload
  2. Load the interface based on that value

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