SDK

Adding the SDK to your project

To add our SDK to your own application, you should add it to the build process of your application. Currently we only support doing this using Gradle.
Adding the SDK to your gradle build file consist of two steps:

Adding the repository

To add the repository to your project, open the settings.gradle file in your application.
Edit the repositories part of your settings.gradle, so that it contains the following: 

                        
maven {
    credentials {
        username 'ExampleUsername'
        password 'ExamplePassword'
    }
    url "https://custom-ocr.klippa.com/sdk/android/maven"
}
maven { url "https://jitpack.io" }
                        
                    
                        
maven {
    credentials {
        username = "ExampleUsername"
        password = "ExamplePassword"
    }
    setUrl("https://custom-ocr.klippa.com/sdk/android/maven")
}
maven { setUrl("https://jitpack.io") }

We add jitpack.io because some of our dependencies are hosted there. If your settings.gradle already contains jitpack.io, don't add it.
The full repositories section of your settings.gradle might look like this now: 

                        
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven {
            credentials {
                username 'ExampleUsername'
                password 'ExamplePassword'
            }
            url "https://custom-ocr.klippa.com/sdk/android/maven"
        }
        maven { url "https://jitpack.io" }
    }
}
                        
                    
                        
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            credentials {
                username = "ExampleUsername"
                password = "ExamplePassword"
            }
            setUrl("https://custom-ocr.klippa.com/sdk/android/maven")
        }
        maven { setUrl("https://jitpack.io") }
    }
}

Adding the dependency

Edit the dependencies part of your build.gradle, so that it contains the following: 

                        
implementation 'com.klippa:identity_verification:0.7.11'
                        
                    
                        
implementation("com.klippa:identity_verification:0.7.11")

The full dependencies section of your build.gradle might look like this now: 

                        
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'androidx.appcompat:appcompat:1.5.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    testImplementation 'junit:junit:4.12'
    androidTestImplementation 'androidx.test.ext:junit:1.1.0'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.1.1'
    implementation 'com.klippa:identity_verification:0.7.11'
}
                        
                    
                        
dependencies {
    implementation("androidx.core:core-ktx:1.13.1")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
    implementation("com.klippa:identity_verification:0.7.11")
}

When you build your app now, it should download our library as dependency, and with that all dependencies of our library.

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

To start the identity verification, import our package:

                        
// Add to the top of your file
import com.klippa.identity_verification.modules.base.IdentitySession;
                        
                    
                        
// Add to the top of your file
import com.klippa.identity_verification.modules.base.IdentitySession

Then start the session from your own Activity

                        
public class MainActivity extends AppCompatActivity {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // @todo: get a session token from the API through your backend here.
        IdentitySession identitySession = new IdentitySession("{your-session-token}");

        yourButton.setOnClickListener(buttonView ->
            startIdentitySession.launch(identitySession)
        );

    }

    private final ActivityResultLauncher startIdentitySession = registerForActivityResult(new StartIdentitySession(),
        sessionResultCode -> {
            // switch over the `sessionResultCode` and handle accordingly.
        }
    );

}
                        
                    
                        
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // @todo: get a session token from the API through your backend here.
        val identitySession = IdentitySession("{your-session-token}")


        yourButton.setOnClickListener {
            startIdentitySession.launch(identitySession)
        }
    }

    private val startIdentitySession = registerForActivityResult(StartIdentitySession()) { sessionCode ->
        // switch over the `sessionCode` and handle accordingly.
    }
}

Session Codes

When the SDK is finished it will return a IdentitySessionResultCode. The current session codes are:

Note: It's also possible to get a message from each IdentitySessionResultCode by calling message() on the sessionCode

  • FINISHED
  • CONTACT_SUPPORT_PRESSED
  • INSUFFICIENT_PERMISSIONS
  • INVALID_SESSION_TOKEN
  • USER_CANCELED
  • NO_INTERNET_CONNECTION
  • DEVICE_DOES_NOT_SUPPORT_NFC
  • DEVICE_NFC_DISABLED
  • TAKING_PHOTO_FAILED
  • INCORRECT_SESSION_SETUP
  • UNKNOWN_ERROR

Customizing the session

The SDK has a few customizing settings, the following methods are available:

Colors

Add or edit the file android/app/src/main/res/values/colors.xml, add the following:

                    
<color name="kiv_text_color">#FF0000</color>
<color name="kiv_background_color">#000000</color>
<color name="kiv_button_success_color">#4CAF50</color>
<color name="kiv_accent_color">#E91E63</color>
<color name="kiv_button_error_color">#673AB7</color>
<color name="kiv_button_other_color">#333333</color>
<color name="kiv_progress_bar_background_color">#00FFFF</color>
<color name="kiv_progress_bar_foreground_color">#9C27B0</color>
<color name="kiv_camera_success_background_color">#BBAC27</color>

Fonts

You can also replace the fonts by adding the files:

                    
android/app/src/main/res/font/kiv_font.ttf
android/app/src/main/res/font/kiv_font_bold.ttf

Language

We currently support English, Dutch, German, French and Spanish.
Note: It's currently not possible to change the strings. 

                        
identitySession.language = IdentitySession.KIVLanguage.Dutch;
                        
                    
                        
identitySession.language = IdentitySession.KIVLanguage.Dutch

Retry Threshold

To configure how often a user can attempt a task before the contact support button is shown to the user.

                        
identitySession.retryThreshold = 1;
                        
                    
                        
identitySession.retryThreshold = 1

Intro/Success screens

To configure whether to show intro/success screens, add the following to the session:

                        
identitySession.hasIntroScreen = true;
identitySession.hasSuccessScreen = true;
                        
                    
                        
identitySession.hasIntroScreen = true
identitySession.hasSuccessScreen = true

Auto capture

The ability to automatically take a photo of the document when it passes all checks.

                        
identitySession.enableAutoCapture = true;
                        
                    
                        
identitySession.enableAutoCapture = true

Include & Exclude lists

You can edit the include list: the extracted data keys that will be shown to the user after document pictures are processed. Or the exclude list: the extracted data keys that will be hidden for the user after document pictures are processed. 

                        
// Default value:
List<String> includeList = new ArrayList<>(Arrays.asList(
    "DateOfExpiry",
    "DateOfIssue",
    "DocumentNumber",
    "DocumentSubtype",
    "DocumentType",
    "Face",
    "Gender",
    "GivenNames",
    "Height",
    "IssuingCountry",
    "IssuingInstitution",
    "Nationality",
    "PersonalNumber",
    "PlaceOfBirth",
    "Residency",
    "Signature",
    "Surname"
));
identitySession.includeList = includeList;

// Default value (empty):
identitySession.excludeList = new ArrayList<>();
                        
                    
                        
// Default value:
identitySession.includeList = mutableListOf(
    "DateOfBirth",
    "DateOfIssue",
    "DocumentNumber",
    "DocumentSubtype",
    "DocumentType",
    "Face",
    "Gender",
    "GivenNames",
    "Height",
    "IssuingCountry",
    "IssuingInstitution",
    "Nationality",
    "PersonalNumber",
    "PlaceOfBirth",
    "Residency",
    "Signature",
    "Surname"
)

// Default value (empty):
identitySession.excludeList = mutableListOf()

Validation Include & Exclude lists

You can edit the validation include list: the failed validations that are shown to the user. Or the validation exclude list: the failed validations that are hidden from the user.
For more information regarding validations check out the API documentation. 

                        
// Default value:
List<String> validationIncludeList = new ArrayList<>(Arrays.asList(
    "DetectFace",
    "CompareFace",
    "DetectSignature",
    "CompareSignature",
    "CheckRequiredField",
    "MatchSidesFront",
    "MatchSidesBack",
    "FieldValidation",
    "MatchVizMrz",
    "MrzChecksum"
));
identitySession.kivValidationIncludeList = validationIncludeList;

// Default value (empty):
identitySession.kivValidationExcludeList = new ArrayList<>();
                        
                    
                        
identitySession.kivValidationIncludeList = listOf(
    "DetectFace",
    "CompareFace",
    "DetectSignature",
    "CompareSignature",
    "CheckRequiredField",
    "MatchSidesFront",
    "MatchSidesBack",
    "FieldValidation",
    "MatchVizMrz",
    "MrzChecksum"
)

// Default value (empty):
identitySession.kivValidationExcludeList = mutableListOf()

APK size / APK splitting

Because our SDK includes OpenCV, which includes native code which in turn generates a native library (.so file) for every architecture, the APK size can increase quite a bit by using our SDK.
To minimize the impact of the SDK on your app size, you can enable APK splitting in your build.grade, like this: 

                
android {
    // Other options
    splits {
       abi {
           enable true
           universalApk false
           reset()
           include 'arm64-v8a', 'armeabi-v7a', 'x86', 'x86_64'
       }
    }
    // Other options
}

In our example app (which contains not much more than the SDK), this resulted in the following APK files:

  • arm64-v8a.apk: 28MB
  • armeabi-v7a.apk: 15.2MB
  • x86_64.apk: 29.1MB
  • x86.apk: 28.4MB

While creating a single APK file creates a file that is 100.8MB, since most phones are ARM, on average APK splitting will result in a 45MB smaller APK, in those cases the SDK will add between 47-61MB to the APK size.

Please note that all APK files should be signed and uploaded to the Play Store to get a release that works on all devices.

JavaDoc

The JavaDoc of the latest version is available for download here.

Versions

The following versions are available:

Version Gradle dependency JavaDoc
0.7.11 implementation 'com.klippa:identity_verification:0.7.11' Download
0.7.10 implementation 'com.klippa:identity_verification:0.7.10' Download
0.7.9 implementation 'com.klippa:identity_verification:0.7.9' Download
0.7.8 implementation 'com.klippa:identity_verification:0.7.8' Download
0.7.7 implementation 'com.klippa:identity_verification:0.7.7' Download
0.7.6 implementation 'com.klippa:identity_verification:0.7.6' Download
0.7.5 implementation 'com.klippa:identity_verification:0.7.5' Download
0.7.4 implementation 'com.klippa:identity_verification:0.7.4' Download
0.7.3 implementation 'com.klippa:identity_verification:0.7.3' Download
0.7.2 implementation 'com.klippa:identity_verification:0.7.2' Download
0.7.1 implementation 'com.klippa:identity_verification:0.7.1' Download
0.7.0 implementation 'com.klippa:identity_verification:0.7.0' Download
0.6.9 implementation 'com.klippa:identity_verification:0.6.9' Download
0.6.8 implementation 'com.klippa:identity_verification:0.6.8' Download
0.6.7 implementation 'com.klippa:identity_verification:0.6.7' Download
0.6.6 implementation 'com.klippa:identity_verification:0.6.6' Download
0.6.5 implementation 'com.klippa:identity_verification:0.6.5' Download
0.6.4 implementation 'com.klippa:identity_verification:0.6.4' Download
0.6.3 implementation 'com.klippa:identity_verification:0.6.3' Download
0.6.2 implementation 'com.klippa:identity_verification:0.6.2' Download
0.6.1 implementation 'com.klippa:identity_verification:0.6.1' Download
0.6.0 implementation 'com.klippa:identity_verification:0.6.0' Download
0.5.2 implementation 'com.klippa:identity_verification:0.5.2' Download
0.5.1 implementation 'com.klippa:identity_verification:0.5.1' Download
0.5.0 implementation 'com.klippa:identity_verification:0.5.0' Download
0.4.0 implementation 'com.klippa:identity_verification:0.4.0' Download
0.3.0 implementation 'com.klippa:identity_verification:0.3.0' Download
0.2.2 implementation 'com.klippa:identity_verification:0.2.2' Download
0.2.1 implementation 'com.klippa:identity_verification:0.2.1' Download
0.2.0 implementation 'com.klippa:identity_verification:0.2.0' Download
0.1.0 implementation 'com.klippa:identity_verification:0.1.0' Download
0.0.16 implementation 'com.klippa:identity_verification:0.0.16' Download

Changelog

0.7.11

  • Fixed issue where UI would be hidden behind status bar on Android 15.
  • Fixed issue where users could get stuck on selfie validation.

0.7.10

  • Fixed crash where lateinit session was called before being uninitialized.
  • Removed selfie result screen to match iOS.

0.7.9

  • Changed order of results in result screen to match iOS.
  • Changed size of image in result screen to match iOS.

0.7.8

  • Fixed issue where SDK could crash when permission are denied.
  • Fixed issue where SDK could get stuck on the loading screen on API 35+.

0.7.7

  • Changed some localizations to better guide through the flow.

0.7.6

  • Fixed issue where SDK would not start on gradle 8+.
  • Fixed some Dutch translations.

0.7.5

  • Added support for up to 4 liveness tasks.
  • Added image to intro if document_type in FieldValidation was setup when creating a session.
  • Added ability to detect document type and show warning if incorrect document type is shown.
  • Added French and German translations.
  • Changed autoCapture photo taking indication; now just the border changes color.

0.7.4

  • Added new loading animation which tint can be set using kiv_accent_color.
  • Added new IdentitySessionResultCode: INCORRECT_SESSION_SETUP which will be used when the session was configured incorrectly.
  • Added ability automatically take a photo of identity document, this can be enabled using enableAutoCapture on IdentitySession.
  • Added kivValidationIncludeList and kivValidationExcludeList which can be used to include/exclude validations.
  • Fixed issue where MrzChecksumValidation was not being handled correctly.
  • Fixed issue where progress bar did not show in intro screen.
  • Improved identity document detection model.
  • Improved liveliness detection on liveness tasks.

0.7.3

  • Added support for AllowPictureFallback which can be configured when creating a session token.
  • Fixed issue where camera might remain active after taking photos.

0.7.2

  • Improved internal logging.

0.7.1

  • Added tooltip to manual MRZ input button. The tooltip pops up after 10 seconds of unsuccessful attempts of MRZ scanning.
  • Fixed issue where view rotation could return null.

0.7.0

  • IdentityBuilder has been renamed to IdentitySession.
  • IdentitySession must be initialized using a session token.
  • Added StartIdentitySession() contract which will now be used for starting the session.
  • Added IdentitySessionResultCode which returns the result of the IdentitySession
  • Removed IdentityBuilderListener in favor of StartIdentitySession().
  • StartIdentitySession() returns IdentitySessionResultCode enum.
  • Removed KlippaError in favor of IdentitySessionResultCode.
  • Increased MRZ scanning speed.
  • Fixed issue where SDK would crash when moved to background and garbage collected. (SDK now reevaluates the session and handles it accordingly)
  • Fixed issue where some buttons could be spammed causing unexpected SDK states.
  • Removed ability to set colors + fonts on IdentityBuilder please use resources instead (see Customizing the identity verification).
  • Fixed issue where try again button on NFC result screen gave unexpected behavior.

0.6.9

  • Fixed issue where NFC authentication could fail with some identity documents.

0.6.8

  • Added support for data groups 11 and 12.

0.6.7

  • Fixed issue where dependencies could cause unexpected conflicts.

0.6.6

  • Fixed issue where button on NFC intro screen was formatted incorrectly.
  • Added contactSupportButton to NFC screen which is shown after x attempts, the threshold of this can be set with retryThreshold on IdentityBuilder (default is 3). When this button is tapped identityVerificationContactSupportPressed() is called and the session is ended.
  • Added ability to skip backside of passport is detected, which can be enabled by setting SkipPassportBackPicture in the session configuration.

0.6.5

  • Temporarily disabled ID model detection.

0.6.4

  • Added ability to add MRZ manually instead of using MRZ scanner.
  • Added model to detect ID for assistance when taking photo of ID.
  • Fixed issue where NFC PACE authentication always failed.

0.6.3

  • Updated masterList
  • Fixed issue where NFC PACE authentication failure was not being handled correctly.

0.6.2

  • Fixed issue where camera could fail to load after configuration changes.
  • Fixed issue where some classes where being de-initialized too early.
  • Fixed issue where continue button could be dismissed unintentionally.

0.6.1

  • Added touch to focus to MRZ scanner.
  • Increased scanning resolution on MRZ scanner.
  • Decreased MRZ scanner view finder size for improved detection.
  • Decreased scanning times on MRZ scanner.
  • Fixed issue where MRZ scanner stop unexpectedly with some passports.
  • Fixed issue where some errors were not parsed correctly.

0.6.0

  • NFC is no longer required in the AndroidManifest.
  • Added DeviceDoesNotSupportNFC to KlippaError which is returned when NFC is required but the device does support not it.
  • Added DeviceNFCDisabled to KlippaError which is returned when NFC is required but is disabled on the device.

0.5.2

  • Multiple validation errors can now be shown if necessary.

0.5.1

  • Added ability to disable Liveness detection by setting RequiredLivenessCount to 0.
  • Fixed issue where some colors were not being set correctly.
  • Fixed issue where bold font was not being set correctly.
  • Fixed issue where NFC could fail during authentication.

0.5.0

  • Added NFC Support. This can be enabled through the API by setting RequiredNFCScanCount to 1.
  • Fixed issue where ProGuard might remove used classes.
  • User is now prompted if environment is too dark/bright.
  • Decreased size of Liveness detection models.

0.4.0

  • Added Active and Passive Liveness detection during the selfie step, users will now have to complete 2 tasks (tilting their head in x direction) before the selfie is automatically taken.
  • Renamed finished() to identityVerificationFinished().
  • Renamed canceled() to identityVerificationCanceled(withError:).
  • Renamed contactSupportPressed to identityVerificationContactSupportPressed().

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.
  • Increased quality of pictures taken.

0.2.2

  • Fixed issue where permission request could sometimes hide behind activity.
  • Changed kiv_no_camera_permission to always appear if no permission to camera was granted. (Before it only showed for 3.5 seconds)

0.2.1

  • Fixed issue where we no longer require parent app to request camera permissions and if necessary actively ask for permission.

0.2.0

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

  • Adjusted document and selfie screen UI
  • Added callback for support button pressed contactSupportPressed()
  • Added ability to include/exclude data from data verification check screen with builder.includeList and builder.excludeList

0.0.15

  • Fix timeout handling
  • Fix Spanish error string

0.0.14

  • Minor translation improvements
  • Fix Identity Document file display

0.0.13

  • Fix activity not finishing with correct state.
  • Add Spanish as language
  • Change some English string values
  • Finish Dutch translation

0.0.12

  • Fix annotations not being loaded correctly breaking API usage.

0.0.8

  • Allow colors to be properly overwritten.

0.0.7

  • Fix a bug in Gradle that prevented our resources from being included.

0.0.6

  • Add getIntent method to be able to start the activity yourself. Don’t force usage of the listener.

0.0.5

  • Update minification to always include our own package name.

0.0.1

  • Initial version