This document outlines a possible example of how to integrate SheerID into a commercetools ecommerce project.
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.
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
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.
The modified frontend code is publicly available on the SheerID github: https://github.com/sheerid/commercetools-demo-frontend
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
Endpoints used in the current demo:
/api/success-webhookendpoint receiving SheerID verification webhook
/api/updateregister current cart into Redis with session key
/api/verifyfrontend 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-webhookexample, how to use SheerID API to automatically create the webhook
/api/cart-discountsexample, how to list commercetools cart discounts
/api/getcartsexample, getting a list of open carts from commercetools API
/api/webhookexample, creating cart discount using commercetools 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.
The commercetools backend is serving the SUNRISE SPA frontend, and through the admin API, calls the bridge.
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)
You need to install the dependencies with
yarn install --frozen-lockfile, and then you can start the project with
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
Build instructions for deployment
To generate a static version of the frontend, run the following command:
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).
Preparation, this process does not install anything outside of the cloned folder.
- clone the repository to your local machine
npm installto 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
- 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.examplefile, 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
yarn serverto run the bridge application.
- Check that the bridge is running by visiting the server URL indicated by the application.