iOS SDK

Welcome to the Identomat iOS SDK documentation! Here, you'll find everything you need to integrate our ID verification and KYC/AML solutions into your iOS application seamlessly.

Latest release: Version 1.1.129

Integration Document

The Identomat library provides a user identification flow consisting of various steps that combine document type and user image/video for verification.

Following steps are necessary to start a session with identomat API

Get a session token

Configure flags

Get the instance of Identomat SDK

Pass Session Token and handle callback

Start Identomat SDK

Pass additional variables

1. Get a session token

Every identification process has its session token. To start the SDK, we first need to generate a token. To generate the session, we require a Company Key. The Company Key is a string key provided by Identomat.

It’s important to note that the session token must be generated on the server side and sent to the client. Do not include the Company Key in your app.

For demonstration purposes, the session token is being generated in the example app.

Session Token Request:

URL: <domain>/external-api/begin
URL Parameters:
- company_key
- flags

The flags parameter is a JSON object that needs to be converted to a string and URL-encoded to be URL-safe.

Example:

var url = SESSION_URL + "?" + COMPANY_KEY_URL
let flagsDict : [String : Any] =
[
    "language" : "en",
    "liveness" : true,
    "allow_document_upload" : true,
    "skip_document" : false,
    "skip_face" : false,
    "require_face_document" : false,
    "skip_agreement" : false,
    "server" : "human",
    "document_types" : [
        "id"
        "passport"
        "driver_license"
        "residence_license"
    ]
    "allow_general_document_capture" : false,
    "allow_general_document_upload" : false,
    "cascading_identity_verification" : false,
]
let flagsJsonData = try? JSONSerialization.data(withJSONObject: flagsDict, options: .withoutEscapingSlashes)
let flagsJsonString: String = NSString(data: flagsJsonData!, encoding: String.Encoding.utf8.rawValue)! as String
let flagsEncoded = flagsJsonString.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)
url += "&flags=" + flagsEncoded!;

The response from the API call above will be a session token. This session token needs to be passed to the instance of the Identomat object to begin the identification process.

2. Configure flags

The passed flags define the SDK's functionality. Below is an explanation of each flag:

Flag name

Description

Default

Type

"language"

Defines the language of the SDK.

Possible values:

"en"

"liveness"

Defines the method of liveness verification.

If true, users will be required to perform active liveness checks. If false, users will undergo passive liveness checks.

Possible values:

true, false

false

"allow_document_upload"

If true, users can choose between scanning or uploading their documents.

Possible values:

true, false

false

"skip_document"

Skips the ID verification step.

Possible values:

true, false

false

"skip_face"

Skips the liveness check. Possible values: true, false

false

"skip_agreement"

Skips the agreement page. Possible values: true, false

false

"require_face_document"

If true, users are allowed to capture themselves holding a document in their hand.

Possible values:

true, false

false

"document_types"

A list of allowed document types.

Possible values:

If omitted or set to an empty array, all document types are allowed.

<array>

"allow_general_document_upload"

Allows the user to upload a Proof of Address document.

false

"cascading_identity_verification"

Enables cascading identity verification.

false

"server"

Defines whether it is a video call or default SDK method. Possible values:

"human" - Users are connected to an operator through a video call.
"computer" - Uses the default SDK method.

If omitted, the default behavior will be the SDK method.

"requiredHdMedia"

When enabled, the Liveness and ID verification steps require an full HD camera (1080p or higher). If the user’s device does not meet this requirement, a QR code will be displayed, allowing them to continue the process on another device.

false

3. Get the instance of Identomat SDK and pass data

The main class of the Identomat SDK is the IdentomatManager class. IdentomatManager is a singleton class in the Identomat SDK.

To obtain the SDK variable, you can use the following code:

let indetomatSdk = IdentomatManager.getInstance();

Alternatively, you can call IdentomatManager.getInstance() each time, and it will return the same Identomat SDK instance.

4. Pass session token and handle callback

sessionToken – Response from the API: String type.

To pass the session token, we use the setUp function, which can be called like this:

IdentomatManager.getInstance().setUp(token: sessionToken)

The last step is to pass the callback function, which will be triggered after the user finishes interacting with the library. To do this, use the .callback function, which takes a function as an argument:

IdentomatManager.getInstance().callBack(callback: anyfunc)
//anyfunc is (()->Void)? type
//or
IdentomatManager.getInstance().callBack {
   print("finished")
}

IdentomatManager.getInstance().backButtonCallBack(callback: anyfunc)
/anyfunc is (()->Void)? type
//or
IdentomatManager.getInstance().backButtonCallBack {
   print("finished with back button")
}

5. Start Identomat SDK

First, you should obtain the library's starter view, and then present it to the user.

let identomatView = IdentomatManager.getInstance().getIdentomatView()
identomatView.modalPresentationStyle = .fullScreen
self.present(identomatView, animated: true, completion: nil)  //self is UIViewController type class

6. Pass additional variables

To customize Identomat library for the app, we have some additional functions:

setColors(colors: [String : String]) - sets specific colors 2.1 setStringsTableName(tableNme : String) - sets string by the languages file 2.2 setStrings(dict : [String : Any?]) - sets specific text strings
setVariables(variables : [String : Any?]) - sets many customizable varaible
setLogo(view: UIView) - sets loading indicator

Following functions in 5 are DEPRECATED after 0.0.73 version

5.1 setTitleFont(fontname: String, size : Int) - sets header font in library

5.2 setHead1Font(fontname: String, size : Int ) - sets header font in library

5.3 setHead2Font(fontname: String, size : Int ) - sets sub header font in library

5.4 setBodyFont(fontname: String, size : Int ) - sets body text font in library

5.5 skipLivenessInstructions() - skips liveness instructions

5.6 setLivenessIcons(neutralFace: UIImage?, smileFace: UIImage?) - sets liveness icons

5.7 setLivenessRetryIcon(retryIcon: Int?, size : Int) - sets liveness retry panel's main icon, size sets size of icon

5.8 setRetryIcon(retryIcon: Int?, size : Int) - sets document scan view's retry panel's main icon, size sets size of icon

5.9 setCameraDenyIcon(cameraDenyIcon: Int?, size : Int) - sets document scan view's retry panel's main icon

6.0 hideStatusBar(_ bool : Bool), setStatusBarStyle(style : UIStatusBarStyle) - customize status bar

1. Customizing Colors

Use the setColors function to adjust the colors in the library to match the app's theme. Pass a dictionary containing the relevant color keys and their corresponding hex values:

"background_low",
"background_high",
"shadow_color",
"text_primary",
"text_secondary",
"text_placeholder",
"text_disabled",
"text_inverse",
"text_link",
"text_color",
"primary_button",
"primary_button_text",
"secondary_button",
"secondary_button_text",
"document_outer",
"selector_header",
"loading_incidcator_background"
"iteration_text",
"iteration_outer",

Way to pass colors to library:

IdentomatManager.getInstance().setColors(colors: colors)

2. Customizing stings

To customize the strings displayed by the library at specific places, you can use two functions:

setStrings(dict: [String: Any?])
setStringsTableName(tableNme : String)

These are two different methods to customize strings.

The setStrings function takes a dictionary with specific keys for different languages. The structure looks like this:


static var strings : [String : Any?] = [
    "en" : [
        "identomat_agree" : "Yes I Agree",
    ],
    "ru" : [
        "identomat_agree": "Согласен",
    ],
    "es" : [
        "identomat_agree": "Acepto",
    ],
    "ka" : [
        "identomat_agree": "ვეთანხმები",
    ]
]

In the second approach, you use the setStringsTableName(tableName: String) function, where you create a .strings file in your project and localize it for different languages, just like you would do for your app.

Here's how you can use this method:

Create a .strings file, for example, languages.strings.
Localize the file for different languages as you normally would in your project.
Pass the name of the .strings file (without the extension) to the library, like this:

setStringsTableName(tableNme : "languages")

3. Customizing Variables

For every other customization, we use the setVariables(variables: Map<String, Any?>) function, where we pass a key-value pair map of variables.

The map structure looks like this:

static var variables : [String : Any?] = [
    "back_button_icon": UIImage(named: "image_name"),                      -- sets back button icon.               type -> UIImage
    "liveness_neutral_icon" : UIImage(named: "liveness_neutral_icon"),     -- sets liveness neutral face icon.     type -> UIImage
    "liveness_smile_icon" : UIImage(named: "liveness_smile_icon"),         -- sets liveness smile face icon.       type -> UIImage
    "liveness_neutral_icon_record" : UIImage(named: "liveness_neutral_icon"),     -- sets liveness neutral face icon while recording.     type -> UIImage
    "liveness_smile_icon_record" : UIImage(named: "liveness_smile_icon"),         -- sets liveness smile face icon  while recording.      type -> UIImage

    "liveness_retry_icon" : UIImage(named: "image_name"),                          -- sets liveness retry page icon.       type -> UIImage
    "liveness_retry_text_icon_1" : UIImage(named: "image_name"),                          -- sets liveness retry first instruction icon.       type -> UIImage
    "liveness_retry_text_icon_2" : UIImage(named: "image_name"),                          -- sets liveness retry second instruction icon.       type -> UIImage
    "liveness_retry_text_icon_3" : UIImage(named: "image_name"),                          -- sets liveness retry third instruction icon.       type -> UIImage
    "liveness_retry_text_icon_4" : UIImage(named: "image_name"),                          -- sets liveness retry fourth instruction icon.       type -> UIImage
    "scan_retry_icon" : UIImage(named: "image_name"),                              -- sets scan document retry page icon.  type -> UIImage
    "camera_deny_icon" : UIImage(named: "image_name"),                             -- sets camera deny page icon.          type -> UIImage
    "upload_retry_icon" : UIImage(named: "image_name"),                            -- sets upload retry page icon.         type -> UIImage

    "liveness_retry_icon_size" : 200,                                  -- sets save icon sizes.                type -> int
    "scan_retry_icon_size" : 200,
    "camera_deny_icon_size" : 200,
    "upload_retry_icon_size" : 200,
    "liveness_retry_text_icon_1_size: 24,
    "liveness_retry_text_icon_2_size: 24,
    "liveness_retry_text_icon_3_size: 24,
    "liveness_retry_text_icon_4_size: 24,

    "primary_button_width": nil,                       -- sets primary button width, if nil its width is maximum
    "primary_button_height": 50,                       -- sets primary button height,

    "skip_liveness_instructions" : false,              -- skips liveness instructions                          type -> boolean
    "liveness_type" : 1,                               -- chooses liveness icons display type values 1 or 2    type -> int
    "button_corner_radius" : nil,                     -- sets button corner radious, if it's nil button will be round cornered
    "panel_elevation" : 1,                             -- sets panels elevation,                               type -> int

    Sets  font sizes
    "title_medium_size":20,
    "title_small_size":
    "headline_medium_size":20,
    "headline_small_size"
    "body_medium_size":11
    "body_small_size"
 
    Sets font
    "title_font":"font-name",
    "headline_font":"font-name",

    "default_country_code": "GE"                      -- sets default country for country code picker
]

4. Setting a custom logo

setLogo(view: UIView) This function is used for setting a custom logo in the library. You can pass your own custom view, and display anything on that view (animations, images, etc.). This logo will be displayed when the library is processing something.

String keys and default values

String keys and their default value for English language:

"identomat_agree" = "Agree";
"identomat_title" = "";
"identomat_agree_page_title" = "Consent for personal data processing";

"identomat_capture_method_title" = "Choose a method";

"identomat_card_front_instructions" = "Scan FRONT SIDE of ID CARD";
"identomat_card_front_upload" = "Upload FRONT SIDE of ID CARD";
"identomat_card_looks_fine" = "Card looks fine";
"identomat_card_rear_instructions" = "Scan BACK SIDE of ID CARD";
"identomat_card_rear_upload" = "Upload BACK SIDE of ID CARD";

"identomat_choose_file" = "Choose a file";

"identomat_continue" = "Continue";

"identomat_driver_license" = "Driver license";
"identomat_driver_license_front_instructions" = "Scan FRONT SIDE of DRIVER LICENSE";
"identomat_driver_license_front_upload" = "Upload FRONT SIDE of DRIVER LICENSE";
"identomat_driver_license_rear_instructions" = "Scan BACK SIDE of DRIVER LICENSE";
"identomat_driver_license_rear_upload" = "Upload BACK SIDE of DRIVER LICENSE";

"identomat_vehicle_registration_certificate_front="Upload FRONT SIDE of VEHICLE REGISTRATION CERTIFICATE"
"identomat_vehicle_registration_certificate_back="Upload BACK SIDE of VEHICLE REGISTRATION CERTIFICATE"

"identomat_face_instructions" = "Place your FACE within OVAL";
"identomat_face_looks_fine" = "Face looks fine";

"identomat_card" = "ID card";
"identomat_im_ready" = "I'm ready";
"identomat_initializing" = "Initializing...";
"identomat_lets_try" = "Let's try";

"identomat_passport" = "Passport";
"identomat_passport_instructions" = "Passport photo page";
"identomat_passport_upload" = "Upload passport photo page";

"identomat_record_begin_section_1" = "Take a neutral expression";
"identomat_record_begin_section_2" = "Smile on this sign";
"identomat_record_begin_section_3" = "Take a neutral expression again";
"identomat_record_begin_title" = "Get ready for your video selfie";

"identomat_liveness_record_begin_title="Get ready for your video selfie"
"identomat_liveness_record_begin_subtitle="When prompted, repeat the facial expression shown on the icons"
"identomat_liveness_record_begin_section_title="Tips"
"identomat_liveness_record_begin_section_1="First, position your face in the frame"
"identomat_liveness_record_begin_section_2="Hold still until success notify"
"identomat_im_ready="I\'m ready"

"identomat_record_fail_description" = "But first, please take a look at the instructions";
"identomat_record_fail_title" = "Let's try again";
"identomat_record_instructions" = "Place your FACE within OVAL and follow the on-screen instructions";

"identomat_residence_permit" = "Residence permit";
"identomat_residence_permit_front_instructions" = "Scan FRONT SIDE of RESIDENCE PERMIT";
"identomat_residence_permit_front_upload" = "Upload FRONT SIDE of RESIDENCE PERMIT";
"identomat_residence_permit_rear_instructions" = "Scan BACK SIDE of RESIDENCE PERMIT";
"identomat_residence_permit_rear_upload" = "Upload BACK SIDE of RESIDENCE PERMIT";

"identomat_retake_photo" = "Retake photo";
"identomat_retry" = "Retry";
"identomat_scan_code" = "Scan the code";
"identomat_scan_me" = "Scan me";
"identomat_select_document" = "Select document";
"identomat_neutral_expression" = "Neutral face";
"identomat_smile" = "Smile";
"identomat_take_photo" = "Take a photo";
"identomat_upload_another_file" = "Upload another file";
"identomat_not_smile="Smile not detected"
"identomat_eyes_closed="Eyes are closed"
"identomat_face_hold="Hold still"
"identomat_no_face="Face is missing"
"identomat_face_covered="Face is covered"

"identomat_upload_file" = "Upload a file";
"identomat_uploading" = "Uploading...";
"identomat_verifying" = "Verifying...";

"identomat_upload_instructions_1" = "Upload a color image of the entire document";
"identomat_upload_instructions_2" = "JPG or PNG format only";
"identomat_upload_instructions_3" = "Screenshots are not allowed";

"identomat_document_align" = "Frame your document";
"identomat_document_blurry" = "Document is blurry";
"identomat_document_face_blurry" = "Face on document is blurry";
"identomat_document_face_require_brighter" = "Low light";
"identomat_document_face_too_bright" = "Avoid direct light";
"identomat_document_move_away" = "Please move document away";
"identomat_document_move_closer" = "Please move document closer";
"identomat_document_move_down" = "Please move document down";
"identomat_document_move_left" = "Please move document to the left";
"identomat_document_move_right" = "Please move document to the right";
"identomat_document_move_up" = "Please move document up";
"identomat_document_type_unknown" = "Unknown document type";
"identomat_document_covered" = "Document is covered";
"identomat_document_grayscale" = "Document is grayscale";
"identomat_document_format_mismatch" = "Document format mismatch";
"identomat_document_type_mismatch" = "Wrong document";
"identomat_document_not_readable" = "Document not readable";
"identomat_document_face_align" = "Document face align";
"identomat_document_spoofing_detected2" = "Document spoofing detected";
"identomat_document_page_mismatch="Wrong page"
"identomat_face_look_straight="Look straight'
"identomat_face_mismatch="Faces do not match"

"identomat_face_align" = "Frame your face";
"identomat_face_away_from_center" = "Center your Face";
"identomat_face_blurry" = "Face is blurry";
"identomat_face_far_away" = "Move closer";
"identomat_face_require_brighter" = "Low light";
"identomat_face_too_bright" = "Avoid direct light";
"identomat_face_too_close" = "Move away";
"identomat_no_document_in_image" = "Frame your document";
"identomat_smile_detected" = "Get neutral face";
"identomat_upload_success" = "Successfully uploaded!";
"identomat_scan_success" = "Success!";
"identomat_scan_success_info" = "Document scanned successfully, Change it to other side.";
"identomat_liveness_success" = "Liveness completed successfully";
"identomat_camera_permission_title" = "Can't access the camera";
"identomat_camera_permission_text" = "Permission on camera is restricted, without camera, app can't progress forward, please go to settings and check camera permission.";
"identomat_audio_permission_title" = "Can't access the microphone";
"identomat_audio_permission_text" = "Permission on microphone is restricted, without microphone, call can't be made, please go to settings and check audio permission.";

"no_connection" = "No internet connection";

"identomat_scan_retry_title" = "Capture failed";
"identomat_scan_retry_instruction" = "Please try again in better lighting";
"identomat_scan_retry_again" = "Try again";
"identomat_scan_retry_cancel" = "Cancel process";

"identomat_liveness_retry_title" = "We can't detect your face";
"identomat_liveness_retry_instruction" = "";
"identomat_liveness_retry_again = "Try again";
"identomat_liveness_retry_instruction_1" = "Make sure to be in a place with good lighting";
"identomat_liveness_retry_instruction_2" = "Make sure your eyes are clearly visible";
"identomat_liveness_retry_instruction_3" = "Make sure to remove masks or other items that cover your face. Eyeglasses are okay";
"identomat_liveness_retry_instruction_4" = "Make sure to only show your face, we don’t need to see your ID";

"identomat_camera_deny_title" = "Camera access denied";
"identomat_camera_deny_settings" = "Allow access";
"identomat_camera_deny_cancel" = "Cancel process";

"identomat_cascading_instructions=Ready for the task? \n\n When prompted, repeat \n the facial expression shown on the icons: \n\n<b> • Keep neutral face \n • Smile</b> \n\n good luck!
"identomat_cascading_button=Start Liveness Check
"identomat_cascading_neutral_face=Keep neutral face
"identomat_cascading_start=Get ready for liveness check!
"identomat_cascading_smile=Smile!
"identomat_cascading_fail=Liveness Failed
"identomat_cascading_success=That\'s it!

"identomat_resend_code" = "Resend Code";
"identomat_get_code" = "Get Code";
"identomat_sms_title" = "Verify Phone Number";
"identomat_sms_subtitle" = "Enter your correct phone number\nto get verification code";
"identomat_resend_in" = "Resend code in ";
"identomat_invalid_number" = "Please enter valid number";
"identomat_invalid_code" = "The code is not valid";
"identomat_sms_code_sent" = "Enter the 4-digit verification code sent to ";
"identomat_enter_sms_code" = "Enter SMS code";
"identomat_phone_number_hint" = "+1 xxx xxx xxxx";
"identomat_enter_phone_number" = "Enter phone number";
"identomat_enter_correct_phone_number" = "Enter your correct phone number";
"identomat_confirm" = "Confirm";

"identomat_enter_email_address" = "Enter email address";
"identomat_enter_correct_email" = "Enter your correct email address";
"identomat_enter_valid_email" = "Please enter valid email";
"identomat_email_hint" = "example@gmail.com";

"identomat_search=Search

"identomat_agreement_header" = "";
"identomat_require_email_header" = "";
"identomat_require_phone_number_header" = "";
"identomat_require_phone_number_check_header" = "";
"identomat_enter_sms_code_header" = "";
"identomat_select_documents_header" = "";
"identomat_capture_methods_header" = "";
"identomat_upload_header" = "";
"identomat_new_liveness_header" = "";
"identomat_camera_access_header" = "";
"identomat_retry_header" = "";
"identomat_nfc_header" = "";
"identomat_select_country=""

PreviousAndroid SDK changelog NextiOS SDK changelog

Last updated 1 day ago

Was this helpful?