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 or npm 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
- 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 or yarn server to run the bridge application.
Check that the bridge is running by visiting the server URL indicated by the application.