====== 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:
===== 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 =====
LOGIN PAGE
===== 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 ===
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)? ===
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);
}