Native and external apps

While custom apps work only in one store, public applications can be used by thousands of clients. Therefore, they must be able to:

• Have some form of SQL database for managing users and REST API access to their data.

• Provide users with a personal settings page populated with the store data.

• Handle simultaneous access to REST API and settings pages.

When starting public app development, decide how to handle all these processes. Ecwid has two solutions named Native apps and External apps.

Native vs External apps comparison table

Property	Native apps	External apps
Integrated to Ecwid admin	✓	-
Access to store data	Ecwid sendsan encrypted payload as a query param every time users open a settings page. Payload contains details for store identification and REST API access.	Ecwid sends code query param only once when a user installs the app. The code is exchanged for store identification and REST API access which must be safely stored on your side.
Tools for building a settings page	CSS Framework - large collection of functional UI elements, blocks, and page templates following Ecwid admin style guide. Native app JS SDK - collection of JavaScript methods for Native Apps.	-
Required self-hosted endpoints	iframeUrl - user settings page of your app built on HTML. The page loaded inside Ecwid admin when users open the app and provides you with Ecwid API access every time it''s opened.	redirectUrl - handles the authentication process, when users install the app and your app gets access to the store data. openAppUrl - an external settings page/dashboard for your app. It's a URL that allows users to click the "Open app" button in Ecwid admin. However, the URL doesn't carry any data for user identification or Ecwid API access.
Personal user settings storage	App storage - secure storage for user data handled by Ecwid. It has private (available only through REST API) and public parts (also available on the storefront) allowing you to use it, for example, for storefront customizations.	-

Build Native application

Native is the recommended application type for the Ecwid App Market. Check out our guides for managing the store access, user settings page, and storage for user settings below.

• Access store data

• Create user settings page

• Manage personal user settings storage

Build External application

If you already have a working UI on your website, Ecwid won't force you to develop an integrated user settings page. Instead, your app passes an authentication process to identify the store and receive REST API access to its data.

The app must authenticate users only once when they click the "Install" button. At the end of authentication, you receive a store ID and access token for REST API access.

To make an External app, provide us with two endpoints:

• redirectUrl is used in the authentication process when users click the "Install button".

• openAppUrl opens an external dashboard when users click the "Open app" button.

Receive temporary code

The installation process begins when the user clicks the "Install" button in Ecwid admin. When it happens, Ecwid installs the app, then redirects this user to your redirectUrl and calls redirectUrl with an additional code query param.

Request example:

https://www.example.com/myapp?code=abcd1234567890

Here the https://www.example.com/myapp part is redirectUrl, and abcd1234567890 is the code.

That code is temporary and must be exchanged for an access token by your app. It lives for a few minutes and can only be used once in the exchange call.

Exchange code for an access token

This part of the authentication process must be invisible to users. While the code is exchanged in the background, users are still sitting on the redirectUrl.

The exchange request is a POST request calling https://my.ecwid.com/api/oauth/token with a URL-encoded request body. All params in the request body are required and are encoded with the Content-Type: application/x-www-form-urlencoded header.

Request template:

POST /api/oauth/token HTTP/1.1
Host: my.ecwid.com
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code

curl --location 'https://my.ecwid.com/api/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'code={code}' \
--data-urlencode 'redirect_uri={redirect_uri}' \
--data-urlencode 'grant_type=authorization_code'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://my.ecwid.com/api/oauth/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Request body params:

Parameter	Required	Description
client_id	required	client_id of your application. Find it at the bottom of the application Details page on #develop-apps.
client_secret	required	client_secret of your application. Find it at the bottom of the application Details page on #develop-apps.
code	required	The temporary code received on the previous step.
redirect_uri	required	redirectUrl of your application.
grant_type	required	Always authorization_code.

Receive store ID and access token

Ecwid responds to an exchange request with JSON containing store ID and access token details.

Response example:

{
 "access_token":"secret_ab***cd",
 "token_type":"bearer",
 "scope":"read_store_profile update_catalog",
 "store_id":1003,
 "public_token":"public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9"
}

Ecwid responds with JSON-formatted data containing the access token and additional information. Response fields are listed below:

Field	Description
access_token	Secret access token for your app. Use it to authorize REST API requests.
token_type	Always bearer
scope	List of permissions (Access scopes) given to the app. Find all available scopes in Access scopes
store_id	Ecwid store ID.
public_token	Public access token for your app. Ecwid gives it only if an app has public_storefront scope.

Show dashboard page to users

Now you have Ecwid store ID and access to its data, so it's time to redirect them to your dashboard from the redirectUrl. Show them the UI and populate it with the data from their Ecwid store received through REST API.

We recommend processing as many REST API requests as possible in the background and automating UX. For example, if your service requires syncing store products to get started, do not make clients select "Ecwid" platform and click several buttons to start the sync. You know it's an Ecwid user, and you have REST API access to products after the authentication. Automate this process: select "Ecwid" platform for a user, and start products sync immediately.

How to keep users logged in

The openAppUrl doesn't support authentication, so it is impossible to identify a specific Ecwid user when the store owner clicks the "Open app" button and goes to openAppUrl.

If you want to rely on Ecwid for logging in users, we have a workaround solution for it. Email us to discuss how it will work for your application.