commercetools Integrations
This document outlines a possible example of how to integrate SheerID into a commercetools ecommerce project.
Overview
This is a lightweight demo showcasing the ease of integrating SheerID with a commercetools website. As every commercetools site is unique, the demo is not meant to give a feature-complete solution integrating SheerID verification into an existing commercetools website, but to give ideas on how to approach the task and raise questions. The provided frontend code is of no value apart from showing the successful verification, the bridge code is not meant to be used in production, but will help in understanding the integration.
The frontend demo code is using Sunrise SPA, a not feature complete single page application demo system from commercetools. There is no session management implemented, so to implement an end-to-end solution the cart and login handling would need substantial extra work with little value for the demo.
Ways to integrate with SheerID
There are at least three scenarios:
- Give code to the consumer on success / Send code to the consumer via email
- Apply code to shopping session (visible or invisible)
- Send verified signal to the merchant and use the verified status freely
The demo is implementing the third scenario. The first scenario is the easiest to implement, but the consumer needs to enter the code manually.
The second scenario is the most complex to implement from the frontend perspective, but the consumer does not need to enter the code manually.
The third scenario is giving the most freedom, as it can be used to implement integration with any third-party systems and there is no limitation on how the verified customer data can be utilized, stored and reused.
Demo Architecture
The demo consists of two parts, a frontend and a bridge app, connecting to SheerID and commercetools APIs. The frontend is a Sunrise SPA application, the bridge application is written in javascript.
Commercetools Frontend
The simple frontend demo is built from SUNRISE SPA, a simple SPA demo from commercetools (GitHub link) showcasing the simplicity of creating an SPA.
We have made only minimal changes to the demo frontend code:
- footer link (button, see below) linking to the SheerID verification form: we advise having a link in the footer to the verification form
- verified dropdown in the header, showing verified status, name and organization: this is to show the success of the verification process and showcase using the provided data
- minicart panel showing the same information: this is to show the success of the verification process and the provided data
- javascript code saving the verification data into localStorage: as there is no session handling implemented in the SUNRISE SPA demo this is the most convenient way to store the verification data for page reloads
Implementation details
The footer link is creating a random key, session identifier would be used on other frontends. This key is used in the verification form URL as metadata, identifying the frontend session. A simple background process starts in the browser at the same time, polling the bridge with the same key regularly, and waiting for the SheerID webhook to return to the bridge application with verification success. For the demo, we are using a simple polling mechanism, in production a more sophisticated solution would be preferred. Note for example that there is no error handling implemented in the demo, so if the verification fails the frontend will not be notified, still polling the bridge application.
Frontend changes
The modified frontend code is publicly available on the SheerID github: https://github.com/sheerid/commercetools-demo-frontend
Bridge application
The bridge is a simple node.js-based server, accepting requests from the frontend and webhooks from SheerID verification API.
The bridge application’s code is publicly available on the SheerID github: https://github.com/sheerid/commercetools-bridge
Bridge endpoints
Endpoints used in the current demo:
/api/success-webhook
endpoint receiving SheerID verification webhook/api/update
register current cart into Redis with session key/api/verify
frontend endpoint checking verification status
Unused endpoints, containing untested or not necessary code and hints how to extend the functionality of both systems:
/
just a holding page/api/create-webhook
example, how to use SheerID API to automatically create the webhook/api/cart-discounts
example, how to list commercetools cart discounts/api/getcarts
example, getting a list of open carts from commercetools API/api/webhook
example, creating cart discount using commercetools API
SheerID API
The bridge application is using SheerID API and webhooks. The demo is using the verification in test mode, so no real verification is done, but the verification process is fully functional, always returning with success.
commercetools API
The commercetools backend is serving the SUNRISE SPA frontend, and through the admin API, calls the bridge.
Requirements
Running this example requires:
- a commercetools website, access to Merchant Center with a user that has access to the Settings > Developer settings > API keys
- a SheerID account
- computer with node.js v16 or not much higher (should work from v10 and with recent versions but no guarantees)
Frontend build
Development/testing
You need to install the dependencies with yarn install --frozen-lockfile
, and then you can start the project with yarn start
.
If you want to use the default merchant center project there is no need to add a .env
file, if you want to connect to your merchant center project you need to set this up
yarn start
Build instructions for deployment
To generate a static version of the frontend, run the following command:
yarn build
and copy the generated dist
folder to the server. Serve it from an S3 bucket + CloudFlare, nginx, or any other preferred method. Please note that to allow landing pages (browser refresh) to work, you need to configure your server to serve the index.html
file for all requests that are not for existing static files (for example as a custom error document).
Installation
Preparation, this process does not install anything outside of the cloned folder.
- clone the repository to your local machine
- run
yarn
ornpm install
to install the dependencies
Bridge application deployment
How to use:
- Create a commercetools API client in Merchant Center > Settings > Developer settings > API clients
- The scope can be “Admin client” (not recommended) or “Manage” Cart discounts and Discount codes
- Download the created API client’s “Environment variables (.env)” file before closing the popup
- Add the .env file to the project root
- Log in to your SheerID Dashboard
- Create a SheerID program, that you will use e.g. “Student discount”
- Configure your program with eligibility, theme etc
- Set the Codes section to “No Code”
- In Program Settings
- set Webhook for eligible verification to
https://<your_server_address>/api/success-webhook
- add cartid as Campaign Metadata field
- set Webhook for eligible verification to
- Copy the access token from Settings > Access Tokens page
- Edit the downloaded .env file and based on the provided
.env.example
file, add relevant information about your setup, for example:SHEERID_TOKEN=<your copied SheerID Access Token> SHEERID_API_URL=https://services.sheerid.com/rest/v2/ URL=https://www.yourwebsite.com/ PORT=8080 REDIS_HOST=localhost REDIS_PORT=6379
- If you are changing the port, make sure to update the webhook URL in SheerID Dashboard and if you are using Docker or Kubernetes, make sure to update the port in Dockerfile and your deployment files
- Run
node server.js
oryarn server
to run the bridge application. - Check that the bridge is running by visiting the server URL indicated by the application.
Further Reading, Links
Sunrise CommerceTools demo data
https://github.com/sheerid/commercetools-demo-frontend
https://github.com/sheerid/commercetools-bridge