Native vs. External applications

While custom apps work only in one store, public applications are often used by hundreds or thousands of clients. Public applications 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

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 into developing 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 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 with the user clicking 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:

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:

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.