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.4.3/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.4.3/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 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:

  • Handle callbacks
  • Remove the SDK from the page
  • Customise 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}',
  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

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:

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

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.

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

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

Customizing the identity verification

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.

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

Versions

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

Changelog

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