ADUCID 4.x

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[components:binder|ADUCID Binder]], [[nocode:transactions|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:
<sxh javascript>
   <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" />
</sxh>     

===== Basic usage with No-Code =====
Create instance of ADUCID object:
<sxh java>
    var aducid = new ADUCID();
</sxh>

Set addresses of start, check and proxy operation of aducid-binder: 
<sxh java>
   aducid.setStartOperationUrl("/aducid-binder/open");
   aducid.setResultOperationUrl("/aducid-binder/openCheck");
   aducid.setProxyUrl("/aducid-binder/proxy");
</sxh>
        
Override default methods to customize you page:
<sxh java>
   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
      }
   }
</sxh>

Text displayed before operation   
<sxh java>
   aducid.showQRHint = function(param) {
      $('#qr-code-hint').html("Example text - Use your PEIG to authenticate");
   }
</sxh>
   
Text displayed during operation   
<sxh java>
   aducid.showRunningHint = function(param) {
      $('#qr-code-hint').html("Example text - Operation in progress");
   }
</sxh>

===== Web Integration API - Example =====

<sxh html>

<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 running");
        };

        //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>

</sxh>



===== Detailed description =====
See also source file "/aducid-resources/js/aducid-api.js"

==== Communication ====
=== Start operation URL ===
Tell Web API where your start operation is.
<sxh java>
    aducid.setStartOperationUrl = function(param) {
        startOperationUrl = param;
    }
</sxh>

=== Check method location provided by server side controller ===
<sxh java>
    aducid.setResultOperationUrl = function(param) {
        resultOperationUrl = param;
    }
</sxh>

=== Proxy method location ===
<sxh java>
    aducid.setProxyUrl = function(param) {
        proxyUrl = param;
    }

</sxh>

=== Tell AJAX to use GET or POST ===
POST is used to deliver more data like transaction parameters
<sxh java>
    aducid.setAjaxMethod = function(param) {
        ajaxMethod = param;
    }
</sxh>

=== 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.
<sxh java>
    aducid.setRedirectUrl = function(param) {
        redirectUrl = param;
    }
</sxh>

=== 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.
<sxh java>
    aducid.setErrorPage = function(param) {
        errorPage = param;
    }
</sxh>

=== Final action ===
What API should do when operation finishes (not processed on iOS as we use returnUrl directly there)
<sxh java>
    aducid.processResult = function(result) {
        alert(result);
    }
</sxh>

=== Use push ===
Tell Web API if it should use push (QR code was used previously).
<sxh java>
    this.setPush = function(param) {
        push = param == true;
    }
</sxh>
==== UI methods ====
=== Tell server to generate QR / or not to reduce payload ===
<sxh java>
    aducid.setGenerateQr = function(param) {
        generateQr = param;
    }
</sxh>

=== QR code targeting using jQuery ===
<sxh java>
    aducid.setQrCode = function(param) {
        qrCode = param;
    }
</sxh>

=== QR code text hint jQuery ===
<sxh java>
    aducid.setQrHint = function(param) {
        qrHint = param;
    }
</sxh>

=== Button bound operation ===
<sxh java>
    aducid.setButton = function(param) {
        aducidButton = param;
        param.click(function() {
            if (currentRequest != null) instance.startOperation();
            else instance.init(true);
        });
    }
</sxh>
=== Text hint shown before operation started ===
<sxh java>
    aducid.showQRHint = function(param) {
        if (qrHint != null) qrHint.html(localize("aducid_common_authenticateComment"));
    }
</sxh>

=== How API can hide text hint ===
<sxh java>
    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"));
    }
</sxh>

=== How API can hide text hint ===
<sxh java>
    aducid.hideRunningHint = function(param) {
        if (qrHint != null) qrHint.html("");
    }
</sxh>
=== Auxiliary method to animate operation in progress ===
<sxh java>
    aducid.startAnimation = function() {
        if (qrCode != null) {
            qrCode.show();
            qrCode.attr("src", "/aducid-resources/img/running.gif");
        }
    }
</sxh>
    
=== Stop animation ===
<sxh java>
    aducid.stopRunningAnimation = function() {
        if (qrCode == null) return;
        qrCode.hide();
    }
</sxh>
==== Advanced methods ====
=== Init Params ===
Method to pass more parameters like transaction amount, description, etc.
<sxh java>
    aducid.setInitParams = function(param) {
        initParams = param;
    }
</sxh>

=== Debug DOM to display internal messages ===
<sxh java>
    aducid.setDebug = function(param) {
        aducidDebug = param;
    }
</sxh>

=== Is binding URI? ===
<sxh java>
    aducid.isURI = function() {
        return instance.getSessionBinding() == "URI";
    }
</sxh>
    
=== Is binding QR? ===
<sxh java>
    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);
    }
</sxh>

=== Get last binding mode ===
<sxh java>
    aducid.getSessionBinding = function() {
        return localStorage['session-binding'];
    }
</sxh>

=== How PEIG not installed is treated, marketplace redirect can be used here ===
<sxh java>
    aducid.showPeigError = function() {
        alert("peig error - override this function")
    }
</sxh>

=== How errors are treated - use nice dialogues here ===
<sxh java>
    aducid.handleError = function(e) {
        alert(e);
    }
</sxh>
ADUCID 4.x

User Tools

Site Tools

Page Tools
