E-Com Plus app for direct integration with Jadlog carrier
-
Start creating a Firebase project:
- Analytics is not needed;
- Set a nice project name (ID) and remember it;
-
Enter the project, go to databases page (on menu) and create database:
- Just bypass with default production mode and rules;
-
Firebase free plan doesn't support sending external HTTP requests, so you'll need to upgrade to Blaze (on demand) plan;
-
Get your Firebase token from CLI:
npm install -g firebase-tools
firebase login:ci
-
Use this template to generate a new repository for your application;
-
Go to your repository settings tab and set the following secrets:
FIREBASE_PROJECT_ID
: The ID (name) of your Firebase project;FIREBASE_TOKEN
: The token generated withfirebase-tools
;SERVER_OPERATOR_TOKEN
: Random (at least 16 bytes) admin token generated from CLI or here;MARKET_TOKEN
(optional): Your E-Com Plus Market personal token to publish the app automatically;
Almost ready, time to โ and code!
Edit functions/ecom.config.js
to set correct app_id
, title
and optionally more fields on base app body.
If you're not yet familiarized with this boilerplate, read with attention the comments and instructions at the configuration file. You can also setup procedures from there to specify the web-hooks your app should receive.
All endpoints inside /ecom/
path MUST BE PRIVATE (trey are by default), accessible only for E-Com Plus official servers or with X-Operator-Token
header (equal to SERVER_OPERATOR_TOKEN
env).
Requests to E-Com routes must have X-Store-ID
header or store_id
parameter on URL query string.
Handle authentication callback request and save tokens to database, also create Store API procedures if configured.
You can edit it to send custom requests to external server notifying new store installation or setup.
Returns Store API authentication data based on received Store ID, for external usage.
Sample response:
{
"application_id": "a00000000000000000000012",
"application_app_id": 9000,
"store_id": 1011,
"authentication_id": "120000000000000000000012",
"access_token": "eyJhbGciOi.eyYzdWIi.ZEONFh7HgQ"
}
You should consume it if you want to use this boilerplate as an authentication backend only. By getting this data (HTTP GET) you'll be able to run authenticated requests to Store API from your own server, with your preferred language, framework...
Call update service to start refreshing old access tokens.
Receives E-Com Plus notification POSTs for configured procedures.
You may want to edit it to properly treat trigger body and do your custom stuff for each notification type.
Endpoints for E-Com Plus Mods API.
You should edit the respective ones for enabled modules (on
ecom.config.js
).
If the app works with admin_settings
(configuration), use getAppData
to get the application data
/hidden_data
configured by merchant from dashboard through Store API (Application Object).
We recommend treating Store API clients (40x) and server (50x) errors with errorHandling
abstraction.
You may want to use appSdk
to make custom authenticated requests to Store API or deeper coding out of our examples.
- Add third party libraries to
functions/package.json
dependencies; - Add custom web app routes by creating new files to
functions/routes
folder; - Add new methods/handlers at
functions/lib
folder;
Optional setup for Market
You may want to make your app public and available to install within E-Com Plus dashboard, to do this:
- Edit
ecomplus-market.json
to set a short description and category between shipping, sales, tools, customer-service, marketing, inventory or product-sourcing; - Overwrite the default PNG icon at
functions/public/icon.png
; - Write a good markdown description for the app at
functions/public/description.md
; - Take note about publication;
If you are not yet a registered partner, start by filling out this form and wait a little for our response ๐ค
๐ Awesome E-Com Plus applications to get inspired!
Every commit will trigger a new deploy (with GitHub Actions), then your app will be accessible at:
https://us-central1-<project-id>.cloudfunctions.net/app/
๐
The assets/application.json
will be updated automatically with some package info and current Cloud Function endpoints, you can use it as body to Create new Application on Store API.
You can skip deploy workflow by adding
[skip ci]
to the commit message.
Also, your app's access tokens to Store API will be automatically refreshed every 8 hours by scheduled workflow.
If MARKET_TOKEN
secret is set, the app will be automatically published to Market every time assets/application.json
is changed, then merchants will be able to install it with up to date version.
Setup the project normally by cloning your repository and installing npm dependencies:
git clone [email protected]:$username/$app_repository.git
cd $app_repository
npm i
cd functions
npm i
Then you can call npm run deploy
locally getting configuration from .env
file on project root. You can also set a different FIREBASE_PROJECT_ID
locally for test purpose only.
When you're done, you can publish the app by running npm run publish:market
.
You can also use firebase-tools
CLI to run tests/deploy with custom config or scripts.