SDK

Including the SDK library in your webpage

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.

Include the 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.6.0/klippa.min.js"></script>

Include the css tag

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.6.0/style.css"/>

Note: you can also download the Javascript and CSS to serve it from your website assets.

Adding basic HTML markup

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>

Creating sessions

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.

Starting the identity verification

You are now ready to initialize 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}',
  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**

Getting Started

You can start using the SDK by copying this fully functional HTML example of a minimal implementation.

                    
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Klippa ID Verification</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.6.0/klippa.min.js"></script>
    <link href="https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.6.0/style.css"/>
</head>
<body>
    <div id='klippa-identity-verification'></div>
    <script>
        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
            }
        });
    </script>
</body>
</html>

Congratulations! You have successfully started the flow. Carry on reading the next sections to learn how to:

  • Handle callbacks
  • Remove the SDK from the page
  • Customize the SDK
  • Create checks

Handling callbacks

onComplete

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}',
  onComplete: function(data) {
    console.log("everything is complete")
    // You can now trigger your backend to validate the session and continue
  }
})

onFinish

onFinish {Function(session)} optional

Callback that fires when the user has finished all the steps.

Param:

  • session: this function returns a full object of the latest session information, which looks like this:

                        
{
    apiBasePath: "",
    error: "",
    initialized: true,
    isLoading: false,
    session: {} // holds the full session information that comes back from the back-end API
    status: {
      // Depending on your config this will return status flags for each step in the flow, for example:
      PendingIDBackPicturesCount: 0,
      PendingIDFrontPicturesCount: 0,
      PendingSelfiesCount: 0,
      PendingSignatures: 0,
      Step: "Finished"
    },
    token: "",
    validations: [] // array with validations for documents including their status
}

Here is an onFinish callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onFinish: function(session) {
    console.log("Finished!");
    console.log(session);
  },
})

onError

onError {Function} optional

Callback that fires when an error occurs. The callback returns the following errors types:

exception: This type will be returned for the following errors:

  • Timeout and server errors
  • Authorization
  • Invalid token

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"
}

Here is an onError callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onError: function(event) {
    console.log(event);
  },
})

onModalRequestClose

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.

Here is an onModalRequestClose callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onModalRequestClose: function() {
    console.log("request to close!");
    // Update options with the state of the modal
    KlippaDemo.setOptions({ isModalOpen: false });
  }
})

onSessionStarted

onSessionStarted {Function(session)} optional

Callback that fires after the session is loaded & initialized successfully (on page load/refresh).

Param:

  • session: returns a full session object. See onFinish for example of the response.

Here is an onSessionStarted callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onSessionStarted: function(session) {
    console.log("session started!");
    console.log(session);
  },
})

onPhotoCapture

onPhotoCapture {Function({ file, session })} optional

Callback that fires after a photo was made in the front-end.

Params:

  • file: returns the information of the photo that was just made, this looks like this:

                        
{
  type: "PictureIDFront" | "PictureIDBack" | "Selfie";
  currentStepIndex: number;
  currentFlow: string;
  file: Blob;
}

  • session: returns a full session object. See onFinish for example of the response.

Here is an onPhotoCapture callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onPhotoCapture: function(data) {
    console.log("photo captured!");
    console.log(data);
  },
})

onFileUploaded

onFileUploaded {Function({ file, session })} optional

Callback that fires after a photo was successfully uploaded to the back-end API.

Params:

  • file: returns the information of the photo that was just made, this looks like this:

                        
{
  type: "PictureIDFront" | "PictureIDBack" | "Selfie";
  currentStepIndex: number;
  currentFlow: string;
  file: Blob;
}
  • session: returns a full session object after upload to the API. See onFinish for example of the response.

Here is an onFileUploaded callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onFileUploaded: function(data) {
    console.log("file uploaded!");
    console.log(data);
  },
})

onStepChange

onStepChange {Function({ previousStep, nextStep, session })} optional

Callback that fires after a (sub)step has changed. This can be a substep of the same flow, or when a user jumps to a new flow.

Params:

  • previousStep: returns the information of the previous step:

                        
{
  flow: string; // Intro|TakePictureIDFront|TakePictureIDBack|ExtractedData|TakeSelfie|CaptureSignature|Finished|Failure
  step: number; // The substep of the current flow
}
  • nextStep: returns the information of the new step, see previousStep for an example of the object.

  • session: returns a full session object after upload to the API. See onFinish for example of the response.

Here is an onStepChange callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onStepChange: function(data) {
    console.log("step changed!");
    console.log(data);
  },
})

onFlowChange

onFlowChange {Function({ previousStep, nextStep, session })} optional

Callback that fires after the flow has changed. For example when a user switches from Intro to TakePictureIDFront

Params:

  • previousStep: returns the information of the previous step:

                        
{
  flow: string; // Intro|TakePictureIDFront|TakePictureIDBack|ExtractedData|TakeSelfie|CaptureSignature|Finished|Failure
  step: number; // The substep of the current flow
}
  • nextStep: returns the information of the new step, see previousStep for an example of the object.

  • session: returns a full session object after upload to the API. See onFinish for example of the response.

Here is an onFlowChange callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onFlowChange: function(data) {
    console.log("flow changed!");
    console.log(data);
  },
})

onSupportButtonPressed

onSupportButtonPressed {Function(session)} optional

Callback that fires after the user clicks on the "Contact Support" button. This callback is only used in the Failure step.

Param:

  • session: returns the current session object. See onFinish for example of the response.

Here is an onSupportButtonPressed callback example:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  onSupportButtonPressed: function(data) {
    console.log("support button pressed!");
    console.log(data);
  },
})

Example

Here you can find an entire example with all the callbacks together:

                    
const KlippaDemo = window.KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  containerId: "klippa-identity-verification",

  onComplete: function(event) {
    console.log(event);
  },

  onFinish: function(session) {
    console.log("Finished!");
    console.log(session);
  },

  onError: function(event) {
    console.log(event);
  },

  onModalRequestClose: function() {
      console.log("request to close!");
      // Update options with the state of the modal
      KlippaDemo.setOptions({ isModalOpen: false });
  },

  onSessionStarted: function(session) {
    console.log("session started!");
    console.log(session);
  },

  onPhotoCapture: function(data) {
    console.log("photo captured!");
    console.log(data);
  },

  onFileUploaded: function(data) {
    console.log("file uploaded!");
    console.log(data);
  },

  onStepChange: function(data) {
    console.log("step changed!");
    console.log(data);
  },

  onFlowChange: function(data) {
    console.log("flow changed!");
    console.log(data);
  },

  onSupportButtonPressed: function(data) {
      console.log("support button pressed!");
      console.log(data);
  },
});

Removing the SDK

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-initialize the SDK inside the same webpage later on.

                    
klippaOut = KlippaIDVerification.init({...})
...
klippaOut.tearDown()

Customizing the identity verification

The SDK offers a variety of customization settings, and the following options are available:

token

token {String} required

An auth token is required in order to authorize with the Klippa API. If one isn’t present, an exception will be thrown. 

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
})

containerId

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".

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  containerId: 'klippa-identity-verification',
})

apiBasePath

apiBasePath {String} optional

Optional base URL that overrides the API basePath that is used to make requests to the backend.

The default ID is "".

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  apiBasePath:: '',
})

getTokenFromUrl

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.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  getTokenFromUrl: false,
})

urlTokenKey

urlTokenKey {String} optional

The query string parameter that will be used to get the token when getTokenFromUrl is enabled.

Default value is "token".

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  urlTokenKey: "token",
})

useModal

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({
        token: {insert-session-token-here},
        useModal: true,
        isModalOpen: true,

        onModalRequestClose: function() {
            // Update options with the state of the modal
            klippa.setOptions({isModalOpen: false})
        },
        
        onComplete: function(data) {
            // callback for when everything is complete
            console.log("everything is complete")
        }
    });
};

To call the SDK as a modal, you can trigger it from a button. For example:

                    
<!-- Use a button to trigger the Klippa SDK UI  -->
<button onClick="triggerKlippa()">Verify identity</button>
<div id='klippa-identity-verification'></div>

isModalOpen

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.

Example:

                    
...
onModalRequestClose: function() {
    // Update options with the state of the modal
    klippa.setOptions({ isModalOpen: true });
},
...

shouldCloseOnOverlayClick

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.

The default value is true.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  shouldCloseOnOverlayClick: true,
})

language

language {String} optional

The SDK language can be customized by passing a language string. At the moment, we support and maintain translations for English (default), Dutch, German, Spanish, and French using respectively the following locale tags: en, nl, de, es, fr. 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.

The default value is "en".

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  language: "en",
})

messages

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: 

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  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 successfully 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"
            },
            onIncomplete: {
                title: "Oops! Your identity could not be verified.",
                description: "You can still start using the application by using the launch button below, we will verify your identity manually.",
                buttonText: "Launch app"
            }
        }
    },
    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"
            }
        },
        FieldValidation: {
            ApplicationNumber: "The application number has not passed the validation",
            CountryCode: "The country code has not passed the validation",
            CountryOfBirth: "The country of birth has not passed the validation",
            DateOfBirth: "The date of birth has not passed the validation",
            DateOfExpiry: "The date of expiry has not passed the validation",
            DateOfIssue: "The date of issue has not passed the validation",
            DocumentNumber: "The document number has not passed the validation",
            DocumentSubType: "The document subtype has not passed the validation",
            DocumentType: "The document type has not passed the validation",
            Gender: "The gender has not passed the validation",
            GivenNames: "The given names have not passed the validation",
            Height: "The height has not passed the validation",
            IssuingCountry: "The issuing country has not passed the validation",
            IssuingInstitution: "The issuing institution has not passed the validation",
            MaidenName: "The maiden name has not passed the validation",
            MRZ: "The mrz has not passed the validation",
            Nationality: "The nationality has not passed the validation",
            PartnerName: "The partner name has not passed the validation",
            PersonalNumber: "The personal number has not passed the validation",
            PlaceOfBirth: "The place of birth has not passed the validation",
            Residency: "The residency has not passed the validation",
            SponsorshipNumber: "The sponsorship number has not passed the validation",
            Surname: "The surname has not passed the validation",
            VisaNumber: "The visa number has not passed the validation",
            Weight: "The weight has not passed the validation"
        },
        MrzChecksum: {
            ChecksumValidationError: "We could not verify this document, please try again or try with a different document."
        },
        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

classes {Object} optional

Additional CSS classes can be added for buttons and links. The following are the current available options:

Example: 

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  classes: {
    introBtn: "", // Start the SDK
    retryCameraPermissionButton: "", // Retry getting camera permission
    reviewPictureRetryBtn: "", // Retry taking the picture in review
    reviewPictureSubmitBtn: "", // Submit the picture in review
    takePictureIDFrontBtn: "", // Take the front picture of the document
    takePictureIDBackBtn: "", // Take the back picture of the document
    takeSelfieBtn: "", // Take a selfie of the user
    extractedDataBtn: "", // Proceed to the next view after showing the extracted data
    retakeIDPicturesBtn: "", // Retake ID pictures in the Extracted Data view
    contactSupportBtn: "", // Link to contact support, opens the email application
    closeModalBtn: "", // Close the modal
    onSuccessBtn: "", // Launch the app when the process is successfully finished
    onFailureBtn: "" // Retry failed steps in case of validation failure
  },
})

colors

colors {Object} optional

The colors that are used in the UI can be altered by passing a colors object. These are the different options: 

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  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
  },
})

fonts

fonts {Object} optional

The fonts used in the UI can be altered by passing a fonts object. The options are normal and bold fonts.

Default value (empty):

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  fonts: {
    fontName: "",
    boldFontName: ""
  },
})

verifyIncludeList

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:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  verifyIncludeList: [
    "DateOfExpiry",
    "DateOfIssue",
    "DocumentNumber",
    "DocumentSubtype",
    "DocumentType",
    "Face",
    "Gender",
    "GivenNames",
    "Height",
    "IssuingCountry",
    "IssuingInstitution",
    "Nationality",
    "PersonalNumber",
    "PlaceOfBirth",
    "Residency",
    "Signature",
    "Surname"
  ],
})

verifyExcludeList

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):

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  verifyExcludeList: [],
})

verifyValidationsIncludeList

verifyValidationsIncludeList {Array} optional

The validations keys that will be shown to the user when there is a validation error 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:

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  verifyValidationsIncludeList: [
    "DetectFace",
    "CompareFace",
    "DetectSignature",
    "CompareSignature",
    "CheckRequiredField",
    "MatchSidesFront",
    "MatchSidesBack",
    "FieldValidation",
    "MrzChecksum",
    "MatchVizMrz",
    "ActiveLiveness"
  ],
})

verifyValidationsExcludeList

verifyValidationsExcludeList {Array} optional

The validations keys that will be hidden for the user when there is a validation error after document pictures are processed. By default all keys are shown, but this option enables you to hide some values (see verifyValidationsIncludeList above):

Default value (empty):

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  verifyValidationsExcludeList: [],
})

qrCodeFallback

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 or show this QR fallback, set qrCodeFallback to false.

The default value is true.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  qrCodeFallback: true,
})

redirectToMobile

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 personal computer, even when a webcam is available.

The default value is false.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  redirectToMobile: false,
})

enableRealtimeFeedback

enableRealtimeFeedback {Boolean} optional

If you want to provide real-time feedback to users when capturing a picture of the document under favorable conditions, you can set the enableRealtimeFeedback option to true. This will activate the real-time feedback, which shows visual messages indicating whether it is a good time to take the picture. When the value of enableRealtimeFeedback is set to false, both real-time feedback and auto-capture features will be disabled.

Note: When enableRealtimeFeedback is set to false, the auto-capture feature will also be disabled. Note: To use the parameter SkipPassportBackPicture from the API, the enableRealtimeFeedback must be set to true.

The default value is false.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  redirectToMobile: true,
})

enableAutoCapture

enableAutoCapture {Boolean} optional

If you want to automatically capture a picture of the document under favorable conditions, you can set the enableAutoCapture option to true. This will activate the auto-capture feature, providing real-time feedback for users and removing the button for manually taking a picture. When the value of enableAutoCapture is set to false, the auto-capture feature is disabled, and the button to take a picture will remain visible.

Note: When enableRealtimeFeedback is set to false, the auto-capture feature will also be disabled.

The default value is false.

                    
KlippaIDVerification.init({
  token: '{insert-session-token-here}',
  enableAutoCapture: false,
})

Changing options in runtime

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 get a new flow.

Versions

The following versions are available:

Version Script URL Stylesheet URL Integrity hashes
0.6.0 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.6.0/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.6.0/style.css Script
Style
0.5.17 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.17/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.17/style.css Script
Style
0.5.16 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.16/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.16/style.css Script
Style
0.5.15 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.15/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.15/style.css Script
Style
0.5.14 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.14/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.14/style.css Script
Style
0.5.13 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.13/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.13/style.css Script
Style
0.5.12 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.12/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.12/style.css Script
Style
0.5.11 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.11/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.11/style.css Script
Style
0.5.10 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.10/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.10/style.css Script
Style
0.5.9 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.9/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.9/style.css Script
Style
0.5.8 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.8/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.8/style.css Script
Style
0.5.7 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.7/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.7/style.css Script
Style
0.5.6 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.6/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.6/style.css Script
Style
0.5.5 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.5/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.5/style.css Script
Style
0.5.4 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.4/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.4/style.css Script
Style
0.5.3 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.3/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.3/style.css Script
Style
0.5.2 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.2/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.2/style.css Script
Style
0.5.1 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.1/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.1/style.css Script
Style
0.5.0 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.0/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.5.0/style.css Script
Style
0.4.4 https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.4/klippa.min.js https://custom-ocr.klippa.com/sdk/web/build/identity_verification/0.4.4/style.css Script
Style
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

Changelog

0.6.0

  • Added redesigned layout to modernize interface and improve usability across the application.
  • Added the feature where the back picture of the passport will be skipped if the model checks it.

0.5.17

  • Fixed a bug where the back picture step wasn’t being skipped when the document presented was a passport
  • Fixed the face image display issue in the Extracted Data step during initial setup

0.5.16

  • Fixed duplicate camera permission alerts in Firefox on Android phones.
  • Added margin to the cropped image when the model is enabled.

0.5.15

  • Fixed camera launch failures on certain devices.
  • Fixed incorrect zoom scaling on selfie and liveness review.

0.5.14

  • Added a camera resolution limit of 2560x1440 to ensure smooth camera operation and prevent server overload from large images.
  • Improved camera selection functionality.
  • Fixed an issue where camera permission errors were not displaying.
  • Changed the file format of the pictures from PNG to JPEG.

0.5.13

  • Added file integrity verification to detect corrupted image uploads.

0.5.12

  • Added selection of the appropriate high-resolution camera for documents.

0.5.11

  • Fixed skipping back picture on retry flow.

0.5.10

  • Improved custom error messages in general.
  • Added custom error message for MatchVizMrz validations.

0.5.9

  • Improved the UI.
  • Fixed manual cropping for documents.

0.5.8

  • Fixed an issue where verifyValidationsIncludeList and verifyValidationsExcludeList were not working as expected.

0.5.7

  • Fixed an issue where camera permissions were not being correctly granted, ensuring that the camera functionality is now accessible as intended.

0.5.6

  • Added logging for better traceability and debugging.
  • Replaced the previous mock contact support email address with the appropriate dummy address.

0.5.5

  • Fixed the issue where the failure screen was displaying before instructing to capture an image of the document’s back side.

0.5.4

  • Fixed the RequiredFields validation errors not showing on Failure screen.

0.5.3

  • Fixed resolution on Android phones. Please note that when using on Android phone with auto-capture and/or live feedback enabled, the document capturing resolution may be lower, which could potentially affect the accuracy of face comparison in the Selfie step.
  • Improved live feedback conditions.
  • Fixed display of Drive License image on Intro screen.

0.5.2

  • Added a new model for better recognition of the back driving license.
  • Added hasSuccessScreen to enable/disable the display of the success screen at the en of the session.
  • Added hasIntroScreen to enable/disable the display of the intro screen at the beginning of the session.
  • Added high resolution for pictures.
  • Fixed the issue of reloading the session when finished.
  • Fixed the flow for field validations.

0.5.1

  • Fixed retry flow for face detection and face mismatch.
  • Fixed the issue where the face image was not displayed after taking only the front picture.

0.5.0

  • Added automatic capturing with real-time visual feedback using enableAutoCapture and enableRealtimeFeedback to enable or disable these features.
  • Added the option to skip the passport back picture, which can be set using the session parameter SkipPassportBackPicture.
  • Added presentation of images for document types on the intro screen.
  • Added translations for French, German, and Spanish.
  • Fixed camera mirroring issue.

0.4.4

  • Improved internal logging.
  • Added progress bar.
  • Added face image to result screen.
  • Added verifyValidationsIncludeList and verifyValidationsExcludeList which can be used to include/exclude validation.
  • Fixed issue where taken photo did not format correctly.
  • Fixed issue where selfie viewfinder was not always centered correctly.
  • Fixed issue where some strings were not being translated correctly.
  • Fixed issue where retry would never allow users to take second liveness or backside photo.
  • Fixed issue where extracted data would not always be shown.

0.4.3

  • Add onSupportButtonPressed() event and documentation, this enables implementers to choose their own flow if the “Support Button” is pressed.
  • Add RetryLimit from API support. Meaning that a specified RetryLimit in the session will automatically forward the user after the amount of retries is surpassed.

0.4.2

  • Fix retry flow that would be stuck if a field validation was the only error. Default resumes at TakePictureIdFront

0.4.1

  • Set default camera resolution to 1280x720. Fallbacks to default camera resolution of device if not possible.

0.4.0

  • Minor update containing new styling classes for buttons reviewPictureRetryBtn and reviewPictureSubmitBtn for the review picture step.
  • Changelog typo fixes.
  • Removed a bug where a succesful validation would show a wrong validation message.
  • Removed a bug where a ) would be appended to the validation messages.
  • Corrected review picture mirroring.

0.3.9

  • Better error messages for field validations

0.3.8

  • Better redirect to mobile flow
  • Mirroring is reset for document pictures for better readability in the review step.

0.3.7

  • Add active liveness. It can be enabled by creating the session with RequiredLivenessCount.

0.3.6

  • Better camera functionality

0.3.5

  • Camera mirroring is now correct for all steps on desktop.
  • Added functionality for passive liveness of photo steps with accompanying error messages

0.3.4

  • Wrong tag and replaced by 0.3.4

0.3.3

  • Fixed bug where camera facing outwards would be rotated

0.3.2

  • Camera is now rotated by 180 degrees with respect to the y-axis.

0.3.1

  • Dutch translations have been added. It can be enabled by setting language: 'nl' in the configuration options.

0.3.0

  • The RequiredFields option now enforces that fields are filled. A session cannot be completed successfully if one of the required fields is missing.
  • The redirectToMobile option has been added.

0.2.0

  • Now uses production API by default (unless you’re making a test/debug build 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.

0.0.1

Initial version