SDK

Adding the Identity Verification 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 support doing this using CocoaPods or Carthage.


To add the repository to your project, open the Podfile, if it does not exist, first run pod init in the root of your project with Xcode closed.
Edit the target part of your application in the Podfile, so that it contains the following, making sure it includes your credentials:

                        
pod 'Klippa-Identity-Verification', podspec: 'https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/latest.podspec'
                        
                    

The full Podfile might look like this now:

                        
# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
    
target 'Your-Project-Name' do
    # Comment the next line if you don't want to use dynamic frameworks
    use_frameworks!
    
    # Pods for Your-Project-Name
    pod 'Klippa-Identity-Verification', podspec: 'https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/latest.podspec'
    
end
                        
                    

When you run pod install now, it should download our library as dependency, and with that all dependencies of our library.
Note: this code always uses the latest version, you can also use a specific version to make sure the SDK won't update without your knowledge.

To add the repository to your project, open the Cartfile, if it does not exists, create a Cartfile alongside your .xcodeproj or .xcworkspace.
Add the following to your Cartfile, making sure it includes your credentials:

                        
binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json"
                        
                    

When you run carthage update now, it should download our library as dependency, and with that all dependencies of our library.
Note: this code always uses the latest version, you can also use a specific version to make sure the SDK won't update without your knowledge.

Updating Info.plist file


Camera

If you want to use the Camera capabilities inside of the Identity SDK please add the following to your Info.plist.

Name
 Privacy - Camera Usage Description

                
<key>NSCameraUsageDescription</key>
<string>Your Camera usage description here.</string>
                
            

Near field communication

If you want to use the Near field communication (NFC) capabilities inside of the Identity SDK please add the following to your Info.plist.

Name
 Privacy - NFC Scan Usage Description

                
<key>NFCReaderUsageDescription</key>
<string>Your NFC usage description here.</string>

Name
 ISO7816 application identifiers for NFC Tag Reader Session

                
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
</array>
            
                

Important: When using NFC also add "Near Field Communication Tag Reading" capability to your app using the Signing & Capabilities pane of the project editor.

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

In the ViewController that you want to launch the identity verification, implement the IdentityBuilderDelegate

                    
// Add to the top of your file
import KlippaIdentityVerification

// Your class definition should look like this.
final class ExampleIdentityVerificationViewController: UIViewController, IdentityBuilderDelegate {

    // ... Rest of your controller code.

    func startIdentityVerification() {
        // @todo: get a session token from the API through your backend here.
        let builder = IdentityBuilder(builderDelegate: self, sessionKey: "{insert-session-token-here}")

        // Build returns a viewController UIViewController that you can present.
        let viewController = builder.build()
        self.present(viewController, animated: true, completion: nil)
    }

    func identityVerificationFinished() {
        print("Finished")
    }

    func identityVerificationCanceled(withError: KlippaError) {
        print("canceled with error: \(withError)")
    }

    func identityVerificationContactSupportPressed() {
        print("identityVerificationContactSupportPressed")
    }

    // ... Rest of your controller code.
}
                    
                

When you want to start the identity verification, for example after a button click, call the startIdentityVerification method.

Note: Currently iOS Simulators are not supported due to incompatible binaries.

Customizing the identity verification

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

Intro & Success

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

                    
builder.hasIntroScreen = true
builder.hasSuccessScreen = true
                    
                

Colors

                    
builder.kivColors.textColor = UIColor.red
builder.kivColors.backgroundColor = UIColor.lightGray
builder.kivColors.progressBarBackground = UIColor.lightGray
builder.kivColors.progressBarForeground = UIColor.orange
builder.kivColors.successColor = UIColor.purple
builder.kivColors.errorColor = UIColor.red
builder.kivColors.otherColor = UIColor.lightGray
                    
                

Fonts

                    
builder.kivFonts.fontName = "ComicSans"
builder.kivFonts.boldFontName = "ComicSans"
                    
                

Language

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

                    
builder.kivLanguage = .Dutch
                    
                

Retry Threshold

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

                    
builder.retryThreshold = 1
                    
                

Auto capture

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

                    
builder.enableAutoCapture = true
                    
                

Verify include list

The extracted data keys that will be shown to the user after the document has been processed.

                    
builder.kivVerifyIncludeList = [
    "DateOfBirth",
    "DateOfIssue",
    "DocumentNumber",
    "DocumentSubtype",
    "DocumentType",
    "Face",
    "Gender",
    "GivenNames",
    "Height",
    "IssuingCountry",
    "IssuingInstitution",
    "Nationality",
    "PersonalNumber",
    "PlaceOfBirth",
    "Residency",
    "Signature",
    "Surname"
]
                    
                

Verify exclude list

The extracted data keys that will be hidden from the user after the document has been processed.

                    
builder.kivVerifyExcludeList = []
                    
                

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.

                    
builder.kivValidationIncludeList = [
    "DetectFace",
    "CompareFace",
    "DetectSignature",
    "CompareSignature",
    "CheckRequiredField",
    "MatchSidesFront",
    "MatchSidesBack",
    "FieldValidation",
    "MatchVizMrz",
    "MrzChecksum"
]

builder.kivValidationIncludeList = []
                    
                

SDK size

The dependency download size itself is 67.3MB when extracted, but it contains builds for multiple architectures, it depends on the architecture of the phone how much the SDK is going to add to the app size:

  • arm64: 32.2MB
  • x86_64-simulator: 35MB

Troubleshooting

Sandbox Issue

In case you encounter issues related to the Sandbox, you can disable the ENABLE_USER_SCRIPT_SANDBOXING by following these steps:

  1. In Xcode select your App project
  2. With your app as the target, go to Build Settings.
  3. In the Build Options group, change User Script Sandboxing to NO.

Apple Silicon Architecture Issue

If you are using a Mac computer with an Apple silicon chip and facing problems building this SDK for iOS simulators, you can resolve this by following these steps:

  1. In Xcode, select your App project.
  2. With your app as the target, go to Build Settings.
  3. In the Architectures group, add a new group for debugging by using the + symbol.
  4. Change Any SDK to iOS Simulator.
  5. Replace Standard Architectures with x86_64.
  6. Repeat steps 1 to 5 for the Pods target.

Versions

The following versions are available:

Version Podspec include URL Cartfile dependency Binary download
0.5.19 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.19.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.19 Fat framework (.xcarchive) | XCFramework
0.5.18 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.18.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.18 Fat framework (.xcarchive) | XCFramework
0.5.17 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.17.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.17 Fat framework (.xcarchive) | XCFramework
0.5.16 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.16.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.16 Fat framework (.xcarchive) | XCFramework
0.5.15 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.15.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.15 Fat framework (.xcarchive) | XCFramework
0.5.14 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.14.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.14 Fat framework (.xcarchive) | XCFramework
0.5.13 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.13.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.13 Fat framework (.xcarchive) | XCFramework
0.5.12 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.12.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.12 Fat framework (.xcarchive) | XCFramework
0.5.11 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.11.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.11 Fat framework (.xcarchive) | XCFramework
0.5.10 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.10.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.10 Fat framework (.xcarchive) | XCFramework
0.5.9 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.9.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.9 Fat framework (.xcarchive) | XCFramework
0.5.8 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.8.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.8 Fat framework (.xcarchive) | XCFramework
0.5.7 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.7.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.7 Fat framework (.xcarchive) | XCFramework
0.5.6 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.6.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.6 Fat framework (.xcarchive) | XCFramework
0.5.5 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.5.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.5 Fat framework (.xcarchive) | XCFramework
0.5.4 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.4.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.4 Fat framework (.xcarchive) | XCFramework
0.5.3 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.3.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.3 Fat framework (.xcarchive) | XCFramework
0.5.2 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.2.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.2 Fat framework (.xcarchive) | XCFramework
0.5.1 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.1.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.1 Fat framework (.xcarchive) | XCFramework
0.5.0 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.5.0.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.5.0 Fat framework (.xcarchive) | XCFramework
0.4.0 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.4.0.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.4.0 Fat framework (.xcarchive) | XCFramework
0.3.0 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.3.0.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.3.0 Fat framework (.xcarchive) | XCFramework
0.2.0 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.2.0.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.2.0 Fat framework (.xcarchive) | XCFramework
0.1.1 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.1.1.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.1.1 Fat framework (.xcarchive) | XCFramework
0.1.0 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.1.0.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.1.0 Fat framework (.xcarchive) | XCFramework
0.0.7 https://custom-ocr.klippa.com/sdk/ios/specrepo/ExampleUsername/ExamplePassword/KlippaIdentityVerification/0.0.7.podspec binary "https://custom-ocr.klippa.com/sdk/ios/carthage/ExampleUsername/ExamplePassword/KlippaIdentityVerification.json" == 0.0.7 Fat framework (.xcarchive) | XCFramework

Changelog

0.5.19

  • Fixed issue where the success screen would always show even when hasSuccessScreen was set to false.
  • Fixed issue where the navigationbar icon tint was always white. KIVColors.otherColor is now used instead.

0.5.18

  • Fixed issue where privacy manifest was in incorrect resources in CocoaPods.

0.5.17

  • Fixed issue where the SDK was not loaded correctly.

0.5.16

  • 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.5.15

  • Added new loading animation, the tint can be set using kivColors.progressBarForeground.
  • Added ability automatically take a photo of identity document, this can be enabled using enableAutoCapture on IdentityBuilder.
  • Added kivValidationIncludeList and kivValidationExcludeList to IdentityBuilder which can be used to include/exclude validations.
  • Added privacy manifest.
  • Improved identity document detection model.

0.5.14

  • Added support for AllowPictureFallback which can be configured when creating a session token.

0.5.13

  • Improved internal logging

0.5.12

  • Added tooltip to manual MRZ input button. The tooltip pops up after 10 seconds of unsuccessful attempts of MRZ scanning.
  • Fixed the issue where MRZ manual input screen components could be visible in the background of the navigation bar.

0.5.11

  • Added support for data groups 11 and 12.
  • Fixed issue where keyboard done button did not appear on some devices in manual MRZ form.
  • Fixed issue where SDK might ask to perform NFC even if it’s already passed successfully.
  • Fixed issue where keyboard could cover manual MRZ form fields.

0.5.10

  • Added ability to skip backside of passport is detected, which can be enabled by setting SkipPassportBackPicture in the session configuration.
  • 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.

0.5.9

  • Temporarily disabled ID model detection.

0.5.8

  • Added model to detect ID for auto capture.
  • Fixed issue where background color of some icons (MRZ form) were not being set correctly.
  • Fixed issue where validation (MRZ form) could pass with whitespace characters.

0.5.7

  • Added ability to add MRZ manually instead of using MRZ scanner.

0.5.6

Fixed

  • Issue where failing an upload task could cause an infinite loop.

0.5.5

Fixed

  • Issue where SDK could crash after giving camera permission.

0.5.4

  • Fixed issue where the textColor was not being set correctly on some textFields.
  • We now return InsufficientPermission error if camera permissions were denied or are restricted.
  • Multiple validation errors can now be shown if necessary.

0.5.3

  • Added ability to disable ActiveLiveness detection by setting RequiredLivenessCount to 0.
  • Fixed issue where session could fail to start.
  • Fixed issue where some colors were not being set correctly.

0.5.2

  • Added field validations. Such as document type, residency, and age.
  • Fixed issue where SDK would throw an error if MatchDocumentSides was set to true.

0.5.1

  • Fixed issue where SDK could throw an error while uploading an identity document image.
  • Fixed issue where SDK could crash if camera stops while showing a warning message.

0.5.0

  • Added NFC Support. This can be enabled through the API by setting RequiredNFCScanCount to 1.

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.
  • Upgraded minimum deployment requirement to iOS 13.0
  • Renamed finishedWithSuccess(response:) to identityVerificationFinished().
  • Renamed canceled() to identityVerificationCanceled(withError:).
  • Renamed contactSupportPressed() to identityVerificationContactSupportPressed().
  • Improved clarity in thrown error messages.

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

  • Added arm64 build for simulator to add support for M1 Macs. Please note that this only work in XCFrameworks (Cocoapods), and not in the fat framework, since you can only have one arm64 binary, and the device binaries already come with an arm64 binary.
  • Fixed bug where sdk would crash if no camera is available. The sdk now gracefully gets cancelled.

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.kivVerifyIncludeList and builder.kivVerifyExcludeList

0.0.5

  • Return viewController in stead of presenting it ourself

0.0.4

  • Rename stuff to be used from ObjC

0.0.3

  • Fix classes that should be exposes to be reachable from ObjC
  • Always use test API for now

0.0.2

  • No changes

0.0.1

  • Initial version