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