SDK
To add our SDK to your own application, you should include the script in your webpage. Currently we only support adding the Javascript directly using a script tag.
Add the following HTML on the page that you want to use the SDK:
<script src="https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.3/klippa.min.js"></script>
Add the following HTML on the page that you want to use the SDK:
<link href="https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.3/style.css"/>
Note: you can also download the Javascript and CSS to serve it from your website assets.
There is only one element required in your HTML, an empty element for the modal interface to mount itself on:
<!-- At the bottom of your page, you need an empty element where the
verification component will be mounted. -->
<div id='klippa-identity-verification'></div>
Before you can start using the identity verification you need to generate a session token in your backend. You can then start the session using your newly generated token. Once the session has been completed you can collect the files and data read by the OCR.
You are now ready to initialise the SDK, add the following code in the function where you want to launch the session:
// @todo: get a session token from the API here.
KlippaIDVerification.init({
token: '{insert-session-token-here}',
// id of the element you want to mount the component on
containerId: 'klippa-identity-verification',
onComplete: function() {
console.log("everything is complete")
// You can now trigger your backend to validate the session and continue
}
})
** Be aware! Make sure to load the SDK over an SSL-connection (https). Otherwise the HTML5 camera will fail to load**
Congratulations! You have successfully started the flow. Carry on reading the next sections to learn how to:
onComplete {Function} optional
Callback that fires when both the document and face have successfully been captured and uploaded. At this point you can trigger your backend to create a check by making a request to the Klippa API.
Here is an onComplete callback example:
KlippaIDVerification.init({
token: '{insert-session-token-here}',
containerId: 'klippa-identity-verification',
onComplete: function(data) {
console.log("everything is complete")
// You can now trigger your backend to validate the session and continue
}
})
onError {Function} optional
Callback that fires when one an error occurs. The callback returns the following errors types:
exception This type will be returned for the following errors:
The data returned by this type of error should be used for debugging purpose.
expired_token This error will be returned when a token is expired. This error type can be used to provide a new token at runtime.
Here is an example of the data returned by the onError callback:
// Example of data returned for an `exception` error type
{
type: "exception",
message: "The request could not be understood by the server, please check your request is correctly formatted"
}
// Example of data returned for an `expired_token` error type
{
type: "expired_token",
message: "The token has expired"
}
onModalRequestClose {Function} optional
Callback that fires when the user attempts to close the modal. It is your responsibility to decide then to close the modal or not by changing the property isModalOpen.
If you are embedding the SDK inside a single page app, you can call the tearDown function to remove the SDK completely from the current webpage. It will reset state and you can safely re-initialise the SDK inside the same webpage later on.
klippaOut = KlippaIDVerification.init({...})
...
klippaOut.tearDown()
The SDK has a few customizing settings, the following methods are available:
token {String} required
A Auth token is required in order to authorise with the Klippa API. If one isn’t present, an exception will be thrown.
getTokenFromUrl {Boolean} optional
It's possible to let the SDK fetch the token from the current URL. By default the SDK will look for a query value by using the key string named token. This could be customized by setting the urlTokenKey option to something else. The default value is false.
urlTokenKey {String} optional
The query string parameter that will be used to get the token when getTokenFromUrl is enabled. Default value is token.
useModal {Boolean} optional
Turns the SDK into a modal, which fades the background and puts the SDK into a contained box.
Example:
var klippa = {};
function triggerKlippa() {
klippa = KlippaIDVerification.init({
useModal: true,
isModalOpen: true,
onModalRequestClose: function() {
// Update options with the state of the modal
klippa.setOptions({isModalOpen: false})
},
token: 'token',
onComplete: function(data) {
// callback for when everything is complete
console.log("everything is complete")
}
});
};
<!-- Use a button to trigger the Klippa SDK UI -->
<button onClick="triggerKlippa()">Verify identity</button>
<div id='klippa-identity-verification'></div>
isModalOpen {Boolean} optional
In case useModal is set to true, this defines whether the modal is open or closed. To change the state of the modal after calling init() you need to later use setOptions() to modify it. The default value is false.
shouldCloseOnOverlayClick {Boolean} optional
In case useModal is set to true, the user by default can close the SDK by clicking on the close button or on the background overlay. You can disable the user from closing the SDK on background overlay click by setting the shouldCloseOnOverlayClick to false.
containerId {String} optional
A string of the ID of the container element that the UI will mount to. This needs to be an empty element. The default ID is klippa-identity-verification.
language {String} optional
The SDK language can be customised by passing a language string. At the moment, we support and maintain translations for English (default) and Dutch using respectively the following locale tags: en, nl. To leverage one of these languages, the language option should be passed as a string containing a supported language tag. If language is not present the default copy will be in English.
messages {Object} optional
The default translation messages can be overridden by providing a messages: {} object to the init method. This will do a deep merge to override only the provided strings.
Example:
messages: {
intro: {
title: "Start your ID verification",
description: "Make sure you have your documents at hand.",
buttonText: "Start now"
}
}
{
"intro": {
"title": "Start your identity verification",
"description": "Make sure you have your identity documents at hand. The process will just take 1 minute.",
"buttonText": "Start now"
},
"steps": {
"takePictureIDFront": {
"straight": {
"title": "Take a picture of the front of your identity document",
"buttonText": "Take picture"
},
"angle": {
"title": "Take another picture of the front of your identity document from an angle",
"buttonText": "Take picture"
}
},
"takePictureIDBack": {
"straight": {
"title": "Take a picture of the back of your identity document",
"buttonText": "Take picture"
},
"angle": {
"title": "Take another picture of the back of your identity document from an angle",
"buttonText": "Take picture"
}
},
"extractedData": {
"title": "This is the data that we extracted. Please validate it:",
"failure": "We were not able to extract any data, please try again",
"explanation": "",
"buttonText": "Go to next step"
},
"takeSelfie": {
"straight": {
"title": "Take a selfie without smiling looking straight into the camera",
"buttonText": "Take picture"
},
"smile": {
"title": "Now take a selfie with a smile looking straight into the camera",
"buttonText": "Take picture"
}
},
"captureSignature": {
"title": "Put a signature in the square below using your finger.",
"description": "Make sure it is similar to the one on your identity documents.",
"signBoxPlaceholder": "Sign in this space",
"buttonText": "Approve signature"
},
"liveness": {
"up": {
"title": "Take a picture with your head tilted upwards"
},
"down": {
"title": "Take a picture with your head tilted downwards"
},
"left": {
"title": "Take a picture with your head tilted leftwards"
},
"right": {
"title": "Take a picture with your head tilted rightwards"
},
"buttonText": "Take picture"
}
},
"general": {
"buttons": {
"retakeIDPictures": "Take ID-pictures again",
"back": "Back",
"contactSupport": "Contact support",
"closeModal": "Close",
"retryCameraPermission": "Click here to try again",
"submit": "Submit",
"retake": "Retake photo"
},
"labels": {
"Surname": "Surname",
"DateOfIssue": "Issue date",
"DateOfBirth": "Date of birth",
"DateOfExpiry": "Expiration date",
"Gender": "Gender",
"DocumentType": "Document type",
"DocumentSubtype": "Document subtype",
"PersonalNumber": "Personal number",
"PlaceOfBirth": "Place of birth",
"Residency": "Residency",
"M": "Male",
"F": "Female",
"X": "Unspecified",
"Signature": "Signature",
"DocumentNumber": "Document number",
"Nationality": "Nationality",
"identity_card": "Identity card",
"passport": "Passport",
"IssuingCountry": "Issuing country",
"IssuingInstitution": "Issuing institution",
"GivenNames": "Given names",
"picture": "Picture",
"Face": "Face",
"Height": "Height"
},
"messages": {
"The session has expired": "The session has expired",
"review": "Review picture",
"redirectToMobile": "Continue on mobile",
"button": {
"copyUrl": "Copy URL"
},
"camera": {
"permissionError": "Oops! We don't have your camera permission or your camera is already in use by another application. Please allow access to your camera in your browser and click 'try again'.",
"cameraInUse": "Oops! Your camera is in use by another process. Please make sure to close other processes that use your camera and try again",
"notDetected": "Camera not detected",
"notDetectedText": " We could not detect a camera to be used for taking the photo.",
"qrCodeText": "Scan this QR code on a mobile device with a webcam/camera to continue your session
",
"qrCodeExplanation": "For the best verification results, our advice is to continue the flow on your mobile. Scan this QR code with your phone and follow the steps, or copy this url and open it on your phone browser"
},
"generalError": "Oops! Something went wrong.",
"onSuccess": {
"title": "Your identity has succesfully been verified!",
"description": "You can now start using application by using the launch button below",
"buttonText": "Launch app",
"icon": "Succeeded icon"
},
"onFailure": {
"title": "Oops! Your identity could not be verified.",
"description": "Please try the failed steps again, or Contact support",
"buttonText": "Retry failed steps"
}
}
},
"validations": {
"id": {
"DetectFace": {
"Success": "Identity document: face detected",
"FaceNotDetected": "Identity document: face not detected"
},
"CompareFace": {
"Success": "Identity document: faces match",
"FacesDoNotMatch": "Identity document: faces do not match",
"Error": "Identity document: could not compare face"
}
},
"selfie": {
"DetectFace": {
"Success": "Selfie: face detected",
"FaceNotDetected": "Selfie: face not detected",
"SelfieNotLive": "Selfie: no live face detected"
},
"CompareFace": {
"Success": "Selfie: faces match",
"FacesDoNotMatch": "Selfie: faces do not match",
"Error": "Selfie: could not compare face"
}
},
"Liveness": {
"ActiveLiveness": {
"Success": "Face check: Face in the right direction",
"SelfieNotLive": "Face check: Photo is not live",
"FaceNotRightDirection": "Face check: Face not in the right direction"
}
},
"RequiredFields": {
"DocumentType": "The document type could not be determined",
"DocumentSubType": "The document sub type could not be determined",
"Nationality": "The nationality could not be found on the document",
"DocumentNumber": "The document number could not be found on the document",
"Surname": "The surname could not be found on the document",
"GivenNames": "The given names could not be found on the document",
"DateOfBirth": "The date of birth could not be found on the document",
"PersonalNumber": "The personal number could not be found on the document",
"PlaceOfBirth": "The place of birth could not be found on the document",
"Gender": "The gender could not be found on the document",
"Height": "The height could not be found on the document",
"DateOfIssue": "The date of issue could not be found on the document",
"DateOfExpiry": "The date of expiry could not be found on the document",
"IssuingCountry": "The issuing country could not be found on the document",
"IssuingInstitution": "The issuing institution could not be found on the document",
"Residency": "The residency could not be found on the document",
"MRZ": "The MRZ of the document could not be found",
"Selfie": "The selfie could not be found",
"Picture": "A picture could not be found",
"CapturedSignature": "A signature could not be found",
"Face": "A face could not be found",
"IdentityDocument": "An identity document could not be found"
}
}
}
classes {Object} optional
Some additional classes can be added for buttons and links. Below are the current available options:
Example:
classes: {
introBtn: '',
takePictureIDFrontBtn: '',
takePictureIDBackBtn: '',
extractedDataBtn: '',
takeSelfieBtn: '',
captureSignatureBtn: '',
retakeIDPicturesBtn: '',
backBtn: '',
contactSupportBtn: '',
closeModalBtn: '',
onSuccessBtn: '',
onFailureBtn: ''
}
colors {Object} optional
The colors that are used in the UI can by altered by passing a colors object. These are the different options:
colors: {
textColor: "#333333", // Main headings
successColor: "#00CC00", // Success buttons
errorColor: "#FF0000", // Error buttons and accents
otherColor: "", // Normal buttons
backgroundColor: "#fff", // Background of the complete widget
progressBarBackground: "#EBEFEF",
progressBarForeground: "" // Inner coloured bar
}
verifyIncludeList {Array} optional
The extracted data keys that will be shown to the user after document pictures are processed. By default, all keys are shown. If this config option is provided, then this array will be used as default items.
Default value:
verifyIncludeList: [
"DateOfExpiry",
"DateOfIssue",
"DocumentNumber",
"DocumentSubtype",
"DocumentType",
"Face",
"Gender",
"GivenNames",
"Height",
"IssuingCountry",
"IssuingInstitution",
"Nationality",
"PersonalNumber",
"PlaceOfBirth",
"Residency",
"Signature",
"Surname"
];
verifyExcludeList {Array} optional
The extracted data keys that will be hidden for the user after document pictures are processed. By default all keys are shown, but this option enables you to hide some values (see verifyIncludeList above):
Default value (empty):
verifyIncludeList: [
"DateOfExpiry",
"DateOfIssue",
"DocumentNumber",
"DocumentSubtype",
"DocumentType",
"Face",
"Gender",
"GivenNames",
"Height",
"IssuingCountry",
"IssuingInstitution",
"Nationality",
"PersonalNumber",
"PlaceOfBirth",
"Residency",
"Signature",
"Surname"
];
qrCodeFallback {Boolean} optional
In case the SDK is being run on a device without camera, the SDK shows a QR code with the current URL so that the user can continue the current session on another device. If you do not want to use / show this QR fallback, set qrCodeFallback to false.
The default value is true.
redirectToMobile {Boolean} optional
In case you want to force a user to a mobile device, set both "qrCodeFallback" and "redirectToMobile" to true. This will always render the QR option on a desktop / laptop, even when a webcam is available.
The default value is false.
It's also possible to change options during runtime:
klipppaOut = KlippaIDVerification.init({...})
...
//Stop using the modal
klipppaOut.setOptions({
useModal: false
});
...
//replace the auth token
klipppaOut.setOptions({ token:"new token" });
...
//Open the modal
klipppaOut.setOptions({ isModalOpen:true });
The new options will be shallowly merged with the previous one. So one can pass only the differences to a get a new flow.
The following versions are available:
| Version | Script URL | Stylesheet URL | Integrity hashes |
|---|---|---|---|
| 0.4.3 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.3/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.3/style.css |
Script
Style |
| 0.4.2 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.2/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.2/style.css |
Script
Style |
| 0.4.1 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.1/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.1/style.css |
Script
Style |
| 0.4.0 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.0/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.0/style.css |
Script
Style |
| 0.3.9 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.9/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.9/style.css |
Script
Style |
| 0.3.8 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.8/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.8/style.css |
Script
Style |
| 0.3.7 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.7/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.7/style.css |
Script
Style |
| 0.3.6 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.6/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.6/style.css |
Script
Style |
| 0.3.5 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.5/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.5/style.css |
Script
Style |
| 0.3.4 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.4/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.4/style.css |
Script
Style |
| 0.3.3 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.3/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.3/style.css |
Script
Style |
| 0.3.2 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.2/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.2/style.css |
Script
Style |
| 0.3.1 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.1/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.1/style.css |
Script
Style |
| 0.3.0 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.0/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.3.0/style.css |
Script
Style |
| 0.2.0 | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.2.0/klippa.min.js | https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.2.0/style.css |
Script
Style |
onSupportButtonPressed() event and documentation, this enables implementers to choose their own flow if the “Support Button” is pressed.RetryLimit from API support. Meaning that a specified RetryLimit in the session will automatically forward the user after the amount of retries is surpassed.TakePictureIdFrontreviewPictureRetryBtn and reviewPictureSubmitBtn for the review picture step.) would be appended to the validation messages.RequiredLivenessCount.language: 'nl' in the configuration options.redirectToMobile option has been added.NODE_ENV=development). Please note that due to this change you will have also have to call the production API (https://custom-ocr.klippa.com) from your backend.Initial version