In the auth process, Ecwid calls your iframe URL like this:
https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532
Where the ?payload=353035362c226163636573735f746f6b656e223a22776d6
is the payload
part containing encrypted store information described below.
Authentication flow
Your application needs an access token for the Ecwid REST API to read and modify Ecwid store orders, products, and other information.
The process of getting an access token is described below:
All Native applications are registered with the Enhanced User Auth, so you can start working on your application's tab right away using server side.
If you need your app to be switched to Enhanced Security User Auth (server-side), please contact us and we will update your app.
The workflow can be divided into three steps:
- Decrypt the payload from Ecwid
- Get store-specific data
- Initialize your application functionality
1. Decrypt the payload from the Ecwid Control Panel
Example of the iframe URL call in server-side apps: https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532
<?php
//
// Get and decrypt the payload from Ecwid
//
// authenticate user in iframe page
function getEcwidPayload($app_secret_key, $data) {
// Get the encryption key (16 first bytes of the app's client_secret key)
$encryption_key = substr($app_secret_key, 0, 16);
// Decrypt payload
$json_data = aes_128_decrypt($encryption_key, $data);
// Decode json
$json_decoded = json_decode($json_data, true);
return $json_decoded;
}
function aes_128_decrypt($key, $data) {
// Ecwid sends data in url-safe base64. Convert the raw data to the original base64 first
$base64_original = str_replace(array('-', '_'), array('+', '/'), $data);
// Get binary data
$decoded = base64_decode($base64_original);
// Initialization vector is the first 16 bytes of the received data
$iv = substr($decoded, 0, 16);
// The payload itself is is the rest of the received data
$payload = substr($decoded, 16);
// Decrypt raw binary payload
$json = openssl_decrypt($payload, "aes-128-cbc", $key, OPENSSL_RAW_DATA, $iv);
//$json = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $payload, MCRYPT_MODE_CBC, $iv); // You can use this instead of openssl_decrupt, if mcrypt is enabled in your system
return $json;
}
// Get payload from the GET and process it
$ecwid_payload = $_GET['payload'];
$client_secret = "0123abcd4567efgh1234567890"; // This is a dummy value. Place your client_secret key here. You received it from Ecwid team in email when registering the app
$result = getEcwidPayload($client_secret, $ecwid_payload);
// Get store info from the payload
$token = $result['access_token'];
$storeId = $result['store_id'];
$lang = $result['lang'];
$viewMode = $result['view_mode'];
if (isset($result['public_token'])){
$public_token = $result['public_token'];
}
// URL Encoded App state passed to the app
if (isset($_GET['app_state'])){
$app_state = $_GET['app_state'];
}
//
// Get store specific data
//
// Get store specific data from storage endpoint
$key = 'color';
$url = 'https://app.ecwid.com/api/v3/' .$storeId. '/storage/' .$key. '?token=' .$token;
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL,$url);
$curlResult = curl_exec($ch);
curl_close($ch);
$curlResult = (json_decode($curlResult));
$color = $curlResult -> {'value'};
if ($color !== null ) {
// set color from storage
} else {
// set default colors
}
//
// Start the flow of your application
// ...
?>
public Dictionary<String, Object> DecodePayload(string payload)
{
byte[] encryptionKey = System.Text.Encoding.ASCII.GetBytes(Environment.GetEnvironmentVariable("ECWID_CLIENT_SECRET").Substring(0, 16));
string original = payload.Replace("-", "+").Replace("_", "/");
byte[] decoded = Convert.FromBase64String(original.PadRight(original.Length + (4 - (original.Length % 4)), '='));
string decodedData = Encoding.UTF8.GetString(decoded
);
Aes aes = new AesManaged
{
Key = encryptionKey,
IV = Encoding.ASCII.GetBytes(decodedData.Substring(0, 16)),
Mode = CipherMode.CBC
};
using (ICryptoTransform cipher = aes.CreateDecryptor())
{
string decrypted;
using (MemoryStream memoryStream = new MemoryStream(decoded))
{
using (CryptoStream cryptoStream = new CryptoStream((Stream)memoryStream, cipher, CryptoStreamMode.Read))
{
using (StreamReader streamReader = new StreamReader((Stream)cryptoStream))
{
decrypted = streamReader.ReadToEnd();
}
}
}
return JsonConvert.DeserializeObject<Dictionary<String, Object>>(decrypted.Substring(15));
}
}
{
"store_id": 1003,
"lang": "en",
"access_token":"xxxxxxxxxxxxxxxx",
"view_mode":"PAGE",
"public_token":"public_ASDlkDASmasdaslkdASkndasANJKLsAf"
}
Name | Type | Description |
---|---|---|
payload | string | Encrypted JSON string containing the authentication information (see the details below) |
cache-killer | string | Random string preventing caching on your server |
app_state | string | Optional URL Encoded app state passed to the app in the URL |
Payload
The payload parameter is an encrypted JSON string, which has the following format in decrypted array state:
Name | Type | Description |
---|---|---|
store_id | number | Ecwid store ID |
lang | string | User language (which is currently set in their Control Panel). Use this parameter to translate your application UI to the user language. |
access_token | string | Secure oAuth token (secret_token) for Ecwid REST API |
public_token | string | Public oAuth token (public_token) for Ecwid REST API |
view_mode | string | Mode used to display the application interface: POPUP , PAGE or INLINE . PAGE is a default mode when app is displayed in a separate tab in Ecwid Control Panel, POPUP is used when the app UI is displayed in a popup on any page of Ecwid CP, INLINE type is used for displaying the interface inside an element on a page where other elements are also present |
Ecwid uses AES-128 to encrypt the payload. The key is the first 16 symbols (128 bit) of your application secret key (client_secret). It is provided when you register an app with us. See a PHP example of decryption to understand receiving and decrypting the payload better.
If you are using C# language
For correct payload decryption, create additional padding to make the payload a multiple of 4:
base64 = base64.PadRight(base64.Length + (4 - (base64.Length % 4)), '=');
2. Get store preferences and data
After completing the first step, you have store details and access to it using Ecwid REST API. Now you can get store-specific information from the storage endpoint or from your local database. The result of the payload decryption will be provided in an array $result
, which you can use to get store ID, access token and language information about a store, that opened your Native app.
Application storage can help you store and access user preferences with the Ecwid REST API.
To save and get store-specific data in the storage endpoint, you can use cURL functionality in PHP or any other way you prefer to access REST API endpoints.
3. Initialize your application functionality
Once you have all the details that you need, you can start the standard planned workflow for your app and operate with Ecwid REST API in the background.