Client API for Web Integration

Web Integration API is an essential part of ADUCID for all web browser scenarios. It connects PEIG, AIM and the browser. Integration API is an essential component of ADUCID Binder, No-Code transacations and many other components.

Integration API is located in aducid-resurces folder (on Tomcat). It requires jQuery and API js and css files: 

   <script type="text/javascript" src="/aducid-resources/js/jquery.min.js"></script>
   <script type="text/javascript" src="/aducid-resources/js/aducid-api.js"></script>
   <link type="text/css" media="screen" href="/aducid-resources/css/aducid.css" rel="stylesheet" />

Basic usage with No-Code

Create instance of ADUCID object: 

    var aducid = new ADUCID();

Set addresses of start, check and proxy operation of aducid-binder: 

   aducid.setStartOperationUrl("/aducid-binder/open");
   aducid.setResultOperationUrl("/aducid-binder/openCheck");
   aducid.setProxyUrl("/aducid-binder/proxy");

Override default methods to customize you page: 

   aducid.processResult = function(result) {
      if (result.status == "OK") {
         //authentication successful - reload page, redirect or display authenticated content
         location.reload();
      }
      else {
         //display error status from result.data.message
      }
   }

Text displayed before operation 

   aducid.showQRHint = function(param) {
      $('#qr-code-hint').html("Example text - Use your PEIG to authenticate");
   }

Text displayed during operation 

   aducid.showRunningHint = function(param) {
      $('#qr-code-hint').html("Example text - Operation in progress");
   }

Web Integration API - Example

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
 
<head>
<script type="text/javascript" src="/aducid-resources/js/jquery.min.js"></script>
<script type="text/javascript" src="/aducid-resources/js/aducid-api.js"></script>
 
<script type="text/javascript">
    var aducid = new ADUCID();
    $(document).ready(function() {
        aducid.setAuthentication();
        aducid.setStartOperationUrl("/aducid-binder/open");
        aducid.setResultOperationUrl("/aducid-binder/openCheck");
        aducid.setProxyUrl("/aducid-binder/proxy");
        aducid.setRedirectUrl("/aducid-binder/");
        aucid.setRedirectUrl("/myapp/authenticated");
        aducid.setErrorPage("/myapp/errorPage");
 
        aducid.processResult = function(result) {
            if (result.status == "OK") {
                alert("Success - status: " + result.status);
                location.href = result.redirect;
            }
            else {
                alert("Error - status: " + result.status);
                location.href = result.redirect;
            }
        }
 
        //handle PEIG not installed error
        aducid.showPeigError = function() {
            alert("peig not found or other error");
        }
 
        //handle communication or other error
        aducid.handleError = function(e) {
            alert(e.data.message);
        }
 
        aducid.showQRHint = function(param) {
            $('#qr-code-hint').html("Scan QR or click button to authenticate");
        }
 
        aducid.showRunningHint = function(param) {
            $('#qr-code-hint').html("Operation is runni­ng");
        };
 
        //GUI mapping
        aducid.setButton($("#main-button"));
        aducid.setQrCode($("#qr-code"));
        aducid.setQrHint($("#qr-code-hint"));
 
        //start
        aducid.init();
    });
</script>
</head>
<body>
 
	<h1>LOGIN PAGE</h1>
	<div>
		<button id="main-button">LOGIN using local PEIG</button>
	</div>
	<img id="qr-code" alt="" />
	<div id="qr-code-hint"></div>
 
</body>
</html>

Detailed description

See also source file “/aducid-resources/js/aducid-api.js”

Communication

Start operation URL

Tell Web API where your start operation is. 

    aducid.setStartOperationUrl = function(param) {
        startOperationUrl = param;
    }

Check method location provided by server side controller

    aducid.setResultOperationUrl = function(param) {
        resultOperationUrl = param;
    }

Proxy method location

    aducid.setProxyUrl = function(param) {
        proxyUrl = param;
    }

Tell AJAX to use GET or POST

POST is used to deliver more data like transaction parameters 

    aducid.setAjaxMethod = function(param) {
        ajaxMethod = param;
    }

Redirect URL set by GUI

This is usuallly set by server side but can be also managed from client side. Server side has higher priority. 

    aducid.setRedirectUrl = function(param) {
        redirectUrl = param;
    }

Error redirect URL set by GUI

This is usuallly set by server side but can be also managed from client side. Server side has higher priority. 

    aducid.setErrorPage = function(param) {
        errorPage = param;
    }

Final action

What API should do when operation finishes (not processed on iOS as we use returnUrl directly there) 

    aducid.processResult = function(result) {
        alert(result);
    }

Use push

Tell Web API if it should use push (QR code was used previously). 

    this.setPush = function(param) {
        push = param == true;
    }

UI methods

Tell server to generate QR / or not to reduce payload

    aducid.setGenerateQr = function(param) {
        generateQr = param;
    }

QR code targeting using jQuery

    aducid.setQrCode = function(param) {
        qrCode = param;
    }

QR code text hint jQuery

    aducid.setQrHint = function(param) {
        qrHint = param;
    }

Button bound operation

    aducid.setButton = function(param) {
        aducidButton = param;
        param.click(function() {
            if (currentRequest != null) instance.startOperation();
            else instance.init(true);
        });
    }

Text hint shown before operation started

    aducid.showQRHint = function(param) {
        if (qrHint != null) qrHint.html(localize("aducid_common_authenticateComment"));
    }

How API can hide text hint

    aducid.hideQRHint = function(param) {
        if (qrHint != null) qrHint.html("");
    }

=== Text hint shown after operation started ===
<sxh java>
    aducid.showRunningHint = function(param) {
        if (qrHint != null) qrHint.html(localize("aducid_common_authenticationProgress"));
    }

How API can hide text hint

    aducid.hideRunningHint = function(param) {
        if (qrHint != null) qrHint.html("");
    }

Auxiliary method to animate operation in progress

    aducid.startAnimation = function() {
        if (qrCode != null) {
            qrCode.show();
            qrCode.attr("src", "/aducid-resources/img/running.gif");
        }
    }

Stop animation

    aducid.stopRunningAnimation = function() {
        if (qrCode == null) return;
        qrCode.hide();
    }

Advanced methods

Init Params

Method to pass more parameters like transaction amount, description, etc. 

    aducid.setInitParams = function(param) {
        initParams = param;
    }

Debug DOM to display internal messages

    aducid.setDebug = function(param) {
        aducidDebug = param;
    }

Is binding URI?

    aducid.isURI = function() {
        return instance.getSessionBinding() == "URI";
    }

Is binding QR?

    aducid.isQR = function() {
        return instance.getSessionBinding() == "QR";
    }

=== Is this operation going to be authentication (i.e. first operation in chain)? ===
<sxh java>
    aducid.setAuthentication = function() {
        instance.setSessionBinding(null);
    }

Get last binding mode

    aducid.getSessionBinding = function() {
        return localStorage['session-binding'];
    }

How PEIG not installed is treated, marketplace redirect can be used here

    aducid.showPeigError = function() {
        alert("peig error - override this function")
    }

How errors are treated - use nice dialogues here

    aducid.handleError = function(e) {
        alert(e);
    }

  • web-integration/client-side.txt
  • Last modified: 2019/08/05 12:46
  • by tjotov