Differences

This shows you the differences between two versions of the page.

--- web-integration:client-side [2019/08/01 09:55]
tjotov created
+++ web-integration:client-side [2019/08/05 12:42]
tjotov [UI methods]
@@ Line 1: / Line 1: @@
-====== ADUCID Web Integration Client API Description ======
+====== Client API for Web Integration ======
-advanced method to pass more parameters like transaction amount, description, etc.
+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.
-    aducid.setInitParams = function(param) {
-        initParams = param;
-    }
-tell server to generate QR / or not to reduce payload
+Integration API is located in aducid-resurces folder (on Tomcat). It requires jQuery and API js and css files:
-    aducid.setGenerateQr = function(param) {
+<sxh javascript>
-        generateQr = param;
+   <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>
-QR code and animation location jQuery
+===== Basic usage with No-Code =====
-    aducid.setQrCode = function(param) {
+Create instance of ADUCID object:
-        qrCode = param;
+<sxh java>
-    }
+    var aducid = new ADUCID();
+</sxh>
-QR code hint jQuery
-    aducid.setQrHint = function(param) {
-        qrHint = param;
-    }
-Embedded timer location
+Set addresses of start, check and proxy operation of aducid-binder:
-    aducid.setQrTimer = function(param) {
+<sxh java>
-        qrTimer = param;
+   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>
-debug DOM to display internal messages
+Text displayed before operation
-    aducid.setDebug = function(param) {
+<sxh java>
-        aducidDebug = param;
+   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 =====
+<code 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>
+</code>
+===== Detailed description =====
+See also source file "/aducid-resources/js/aducid-api.js"
-server URL typically provided by server side controller
+==== 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
+=== Check method location provided by server side controller ===
+<sxh java>
     aducid.setResultOperationUrl = function(param) {
         resultOperationUrl = param;
     }
+</sxh>
-    //URL with proxy method provided  by server
+=== Proxy method location ===
-    //returns status oft running operation from AIM until finish
+<sxh java>
     aducid.setProxyUrl = function(param) {
         proxyUrl = param;
     }
-Tell AJAX to use GET or POST
+</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 for iOS typically provided by server side controler
+=== Redirect URL for iOS typically provided by server side controler ===
+<sxh java>
     aducid.setRedirectUrl = function(param) {
         redirectUrl = param;
     }
+</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 with bound operation
+=== Button bound operation ===
+<sxh java>
     aducid.setButton = function(param) {
         aducidButton = param;
@@ Line 66: / Line 199: @@
         });
     }
+</sxh>
-Internal logic to evaluate API binding mode
+=== Text hint shown before operation started ===
-    aducid.setSessionBinding = function(param) {
+<sxh java>
-        if (param == "QR" || param == "URI") {
-        }
-        else param = "";
-        localStorage['session-binding'] = param;
-    }
-Get last binding mode
-    aducid.getSessionBinding = function() {
-        return localStorage['session-binding'];
-    }
-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)?
-    aducid.setAuthentication = function() {
-        instance.setSessionBinding(null);
-    }
-Text hint shown before operation started
     aducid.showQRHint = function(param) {
         if (qrHint != null) qrHint.html(localize("aducid_common_authenticateComment"));
     }
+</sxh>
-How API can hide text hint
+=== How API can hide text hint ===
+<sxh java>
     aducid.hideQRHint = function(param) {
         if (qrHint != null) qrHint.html("");
     }
-Text hint shown after operation started
+=== 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
+=== How API can hide text hint ===
+<sxh java>
     aducid.hideRunningHint = function(param) {
         if (qrHint != null) qrHint.html("");
     }
+</sxh>
-The most important method - what API should do when operation finishes (not processed on iOS as we use returnUrl directly there)
+=== Auxiliary method to animate operation in progress ===
-    aducid.processResult = function(result) {
+<sxh java>
-        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) {
@@ Line 133: / Line 234: @@
         }
     }
+</sxh>
-Stop animation
+=== 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>
-This method controll progress bar animation. See aducid-api.js
+=== Is binding URI? ===
-   this.startProgressBar = function(animationTime) {
+<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)? ===
-Hide QR timer progress bar
+<sxh java>
-    aducid.hideProgressBar = function() {
+    aducid.setAuthentication = function() {
-        if (qrTimer == null) return;
+        instance.setSessionBinding(null);
-        qrTimer.hide();
-        qrTimer.html("");
     }
+</sxh>
-How errors are treated - use nice dialogues here
+=== Get last binding mode ===
-    aducid.handleError = function(e) {
+<sxh java>
-        alert(e);
+    aducid.getSessionBinding = function() {
+        return localStorage['session-binding'];
     }
+</sxh>
+=== The most important method ===
+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>
+=== 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

Differences

Page Tools