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://zignsec-cdn.azureedge.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.

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

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
<!DOCTYPE html>
<html>
<!-- in the head -->
<head>
    <style>
        html,
        body {
            height: 100%;
            margin: 0;
        }
        #zs-root {
            height: 100%;
            width: 100%;
        }
    </style>
    <script src="https://zignsec-cdn.azureedge.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>

Note : Production iframe url link

https://zignsec-cdn.azureedge.net/scripts/v3/zignsec-websdk-prod.js

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
}
<!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://zignsec-cdn.azureedge.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>

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