Web SDK

WebSDK – Webflows with Zero Cost Integration

The Web SDK is a javaScript from ZignSec that allows merchants to do the  integration without any knowledge of API calls.

This article demonstrates how to start a Swedish BankID and a Online ID Scan respectively, with just plain HTML/JavaScript copy-paste.

  1. First you need to obtain the special web_sdk access token, either from ZignSec support [email protected], or create yourself as explained here.
  2. Add the ZignSec WebSDK js reference and the example code into your web page.
  3. Update the script-lines where the product is selected, the access token is set, and your extra configuration parameters are wired up.
  4. You’re done. Loading the page will start the browser-based (for example) eID login in a frame on the page.
  5.  You can get the result delivered in an email or read it on the Portal for Zero-integration, Or collect results with the ZignSec-standard API call to GET results Server-to-server.

First version allows starting of these products: 

    • BankID-se
    • BankID-no
    • NemID
    • ScanningS

Swagger Links

Test swagger- Swagger UI (zignsec.com)

Prod swagger – Swagger UI (zignsec.com) 

Example for BankID Sweden

Use Frames
<!DOCTYPE html>
<html>
<!-- in the head -->
<head>
    <style>
        html,
        body {
            height: 100%;
             width: 100%;
        }
        #zs-root {
            height: 100%;
            width: 100%;
        }
    </style>
    <script src="https://zignsecstorage.blob.core.windows.net/scripts/v3/zignsec-websdk-test.js"></script>
</head>
<!-- in the body -->
<body>
    <div id="zs-root"></div>
    <script>
      var clientToken = "Your web SDK access token"
        var zs = new ZignSec(clientToken, ZsProduct.SbIdAuth);
        var sessionId = null;

        zs.on('frameLoaded', r => {
            console.log('Frame loaded', r);
        });

        // event emitted when frame loaded
        zs.onFrameLoaded(r => {
            console.log('typed frame loaded', r);
        });

        // creates an iframe in the given element id
        zs.openInIframe("zs-root", {
            personalnumber: 197001102222,
            lookupPersonAddress: true
        }).then(r => {
            console.log('Promise continuation: ', r);
            sessionId = r.id;
            // you can run the following to get the session status on the page (if you don't want to use webhook)
            zs.getSessionStatus(sessionId).then(s => {
                console.log('status', s);
            });

        });
    </script>
</body>
</html>
Due to HTML frames obsolete we recommend to open the content in the current browser tab. Below you can find the sample.
<!DOCTYPE html>
<html>
<!-- in the head -->
<head>
    <style>
        html,
        body {
            height: 100%;
            width: 100%;
        }
        #loading {
            font-size: 32px;
            font-weight: bold;
            color: blue;
        }
    </style>
    <script src="https://zignsecstorage.blob.core.windows.net/scripts/v3/zignsec-websdk-test.js"></script>
</head>
<!-- in the body -->
<body>
    <span id="loading">Loading...</span>
    <script>
      var clientToken = "Your web SDK access token"
      var zs = new ZignSec(clientToken, ZsProduct.SbIdAuth);
      var sessionId = null;

      zs.on('pageLoaded', r => {
        console.log('Page Loaded', r);
      });
      zs.onPageLoaded(r => {
        console.log('typed Page Loaded', r);
      });
      zs.onError(r => {
        var loading = document.getElementById('loading');
        var errors = document.getElementById('errors');

        loading.style.visibility = 'hidden';
        for (var i = 0; i < r.errors.length; i++) {
          errors.innerHTML += '<p>' + r.errors[i].description + '</p>';
        }
      });

      // opens a content in the current browser tab
      zs.openInCurrentBrowserTab({
            personalnumber: 197001102222,
            lookupPersonAddress: true
      }).then(r => {
        console.log('Promise continuation: ', r);
        sessionId = r.id;

        // you can run the following to get the session status on the page (if you don't want to use webhook)
        zs.getSessionStatus(sessionId).then(s => {
          console.log('status', s);
        });
      });
    </script>
</body>
</html>

Some products (including Sweden BankID) support different start options. The options supported are listed below. Start options can be passed as a 3rd parameter to the ZignSec object:

var zs = new ZignSec(clientToken, ZsProduct.SbIdAuth, ZsSbIdStartOptions.SameDevice);

Example for Online ID Scanning

<!DOCTYPE html>
<html>
<!-- in the head -->
<head>
    <style>
        html,
        body {
            height: 100%;
            margin: 0;
        }
        #zs-root {
            height: 100%;
            width: 100%;
        }
    </style>
    <script src="https://zignsecstorage.blob.core.windows.net/scripts/v3/zignsec-websdk-test.js"></script>
</head>
<!-- in the body -->
<body>
    <div id="zs-root"></div>  
    <!-- the usage -->  
    <script>
        (function() {
            var clientToken = "Your web SDK access token";
            var zs = new ZignSec(clientToken, ZsProduct.Scanning);
            var sessionId = null;
            zs.openInIframe("zs-root", {
                relay_state: "your_relay_state",
                analysis_types: ["document", "fraud", "selfie"]
            }).then(r => {
                console.log('Promise continuation: ', r);
                sessionId = r.id;
                // you can run the following to get the session status on the page (if you don't want to use webhook)
                zs.getSessionStatus(sessionId).then(s => {
                    console.log('status', s);
                });
            });
        })();
    </script>
</body>
</html>

How to create the web SDK access token yourself

Request

POST to  https://env-gateway.zignsec.com/api/v3.0/websdk/tokens
where env is API or test 
  authentication is needed

Parameters

ParameterDescriptionRequired
expiresInSecondsAdds possibility to limit the time the token is validNo
POST https://test-gateway.zignsec.com/api/v3.0/websdk/tokens HTTP/1.1
Authorization: API KEY

Response

TokenAccess token to be used to create sessions through the WebSDK



{
    "Token": "5d6816ee-7a08-4a73-afed-3b32ba92d9be",
    "Issued": "2020-03-23T09:14:44.1983656Z",
    "Expiration": null
}

Supported products and start options enums

export enum ZsProduct {
  // Swedish BankID Authentication
  SbIdAuth = 'SbidAuth',
  // Swedish BankID Signing
  SbIdSign = 'SbIdSign',
  // Finnish BankID authenticaton both via the mobile app and through banking.
  FbId = 'FbId',
  // Danish NemID Authentication.
  NemId = 'NemId',
  // Norwegian BankID web Authentication. Forwards to nbid_oidc with loginhint = BID
  NbId = 'NbId',
  // Scanning
  Scanning = 'Scanning'
}

export enum ZsSbIdStartOptions {
  AnyDevice = 'AnyDevice',
  SameDevice = 'SameDevice',
  Default = AnyDevice
}

export enum ZsNbIdStartOptions {
  WebOrMobile = 'WebOrMobile',
  Web = 'Web',
  Mobile = 'Mobile',
  Default = WebOrMobile
}
Copyright © 2021 Zignsec AB. All right reserved