User Tools

Site Tools


web-integration:client-side

This is an old revision of the document!


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 for iOS typically provided by server side controler

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

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;
    }

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'];
    }

The most important method

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

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

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

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

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();
    }

How errors are treated - use nice dialogues here

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

web-integration/client-side.1565008887.txt.gz · Last modified: 2019/08/05 12:41 by tjotov