Teydex iOS Document

This document includes all the required steps, usage examples, and platform-specific technical details for integrating the Teydex library securely and smoothly on the iOS platform.

Version Requirements

To use the Teydex iOS library without issues, you should verify your platform versions.

Platform	Min version
iOS	iOS 15.0
	Swift 5.5
	Xcode 26.1

iOS Swift Package Manager Configuration

Add the KYCFramework package to your project via Swift Package Manager. The library will automatically download all required dependencies for you.

Background Modes Settings

In the Signing & Capabilities tab, make sure the following options are enabled under Background Modes:

• Audio, AirPlay, and Picture in Picture
• Voice over IP
• Background fetch

Info.plist Permissions

You need to add the following descriptions to your app's Info.plist file. These messages will be shown to users when permission requests are displayed:

<key>NSCameraUsageDescription</key>
<string>Grant access so others can see you during video calls</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Grant access so your location can be verified</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Grant access so your location can be verified</string>
<key>NSMicrophoneUsageDescription</key>
<string>Grant access so others can hear you during video calls</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Grant access to save your photos to your photo library</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Grant access to browse your photo library</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>FullAccuracy</key>
    <string>Grant access so your location can be verified</string>
</dict>

Info Screen

The Info screen in your KYC application refers to the informational pages shown before each step. Optionally, you can add the following parameters for each step.

Info Screen Properties

Parameter	Type	Description
setTitleText	String	Specifies the title displayed on the Info screen.
setDescriptionText	String	Specifies the description text displayed on the Info screen.
setButtonText	String	Specifies the text of the button that starts the step on the Info screen.
setAssetImageName	String	Specifies the image displayed on the Info screen.
setLottieFileName	String	Specifies the Lottie animation displayed on the Info screen.
setBullets	[String]	Can be used when you want to provide bullet-point information about the next step.
bulletIconName	@RawRes Int	Can be used to change the icon of the bullet items displayed on the Info screen.
setCancelButtonIsActive	Bool	Enables or disables the cancel button in the upper-right corner of the Info screen. Disabled by default.

Info Screen Usage

let frontInfo = infoTemplate
    .setTitleText("ID Card Front Side")
    .setDescriptionText("Please follow the steps below carefully:")
    .setButtonText("Continue")
    .setLottieFileName("front")
    .setBullets([
        "Place Your ID Card\n" +
        "Hold the front side of your ID card parallel to the phone screen. Position it so that it fits completely within the frame shown on the screen.",
        "Visibility of ID Information\nMake sure all information on the ID card is clearly visible. The details should not be blurry and must be easy to read."
    ])
    .build()

Glare Detection

Starting with v1.3.1, Front, Back, Liveness, and Passport steps support glare detection to help users capture the document under suitable lighting conditions. When the environment is too bright, too dark, or when a glare is detected on the document, a warning message is displayed to the user on the related screen.

The following parameters are available on Front, Back, and Passport steps:

Parameter	Type	Description
isGlareDetectionEnable	Boolean	Enables glare detection for the corresponding step. Default is true for Front and Back, and false for Passport.
glareDetectedText	String	Warning text shown when a glare is detected on the document.
tooBrightText	String	Warning text shown when the environment is too bright.
tooDarkText	String	Warning text shown when the environment is too dark.
multipleDocumentsDetectedText	String	Warning text shown when multiple documents are detected in the camera frame.

For the Liveness step, only ambient-light-related parameters are available:

Parameter	Type	Description
isGlareDetectionEnable	Boolean	Enables ambient light monitoring in the Liveness step. Default is true.
tooBrightText	String	Warning text shown when the environment is too bright.
tooDarkText	String	Warning text shown when the environment is too dark.

note

If any of these parameters is not provided, the SDK falls back to the built-in default warning texts (Turkish).

Step

This section defines the properties used across all steps. These properties are available in every step (Front, Back, Hologram, NFC, Liveness, VideoCall).

Step Properties

Parameter	Type	Description
setInfoView	Info	Used to add an Info screen to the relevant step. Optional.
setTitle	String	Represents the toolbar text displayed in the relevant step.
setStepType	StepType	Specifies the type of the step (.idcardFront, .idcardBack, etc.).
setStepInformationTextToSpeech	String	Represents the text to be spoken at the start of the step.
setIdentifyTimeout	TimeInterval	Specifies the timeout duration for the step. The default value is 30.

Liveness Step Properties

Parameter	Type	Description
setDirectionTextToSpeech	String, String, String, String, String	Specifies the text-to-speech messages for the center, right, left, up, and down directions.

Front Step Usage

let idFrontStep = StepBuilder()
    .setIdentifyTimeout(35)
    .setTitle("Front Side")
    .setInfoView(frontInfo)
    .setStepType(.idcardFront)
    .setStepInformationTextToSpeech("Hold the front side of your ID card parallel to the phone screen. The ID card must be positioned fully inside the frame.")
    .setIsGlareDetectionEnable(true)
    .setGlareDetectedText("There is light reflection. Please hold the document at a different angle.")
    .setTooBrightText("The environment is too bright. Please reduce the light.")
    .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
    .setMultipleDocumentsDetectedText("Please show only one document.")
    .build()

Back Step Usage

let idBacktStep = StepBuilder()
    .setIdentifyTimeout(35)
    .setTitle("Back Side")
    .setInfoView(backInfo)
    .setStepType(.idcardBack)
    .setStepInformationTextToSpeech("Hold the back side of your ID card parallel to the phone screen. Make sure all information is clearly visible.")
    .setIsGlareDetectionEnable(true)
    .setGlareDetectedText("There is light reflection. Please hold the document at a different angle.")
    .setTooBrightText("The environment is too bright. Please reduce the light.")
    .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
    .setMultipleDocumentsDetectedText("Please show only one document.")
    .build()

NFC Step Usage

let nfcStep = StepBuilder()
    .setIdentifyTimeout(35)
    .setTitle("NFC")
    .setInfoView(nfcInfo)
    .setStepType(.nfc)
    .setStepInformationTextToSpeech("Move your ID card close to the back of your phone. Make sure the NFC feature is enabled.")
    .build()

Hologram Step Usage

let hologramStep = StepBuilder()
    .setIdentifyTimeout(35)
    .setTitle("Hologram")
    .setInfoView(hologramInfo)
    .setStepType(.hologram)
    .setStepInformationTextToSpeech("Scan the hologram label on your ID card. The hologram should appear bright and clear.")
    .build()

Liveness Step Usage

let faceStep = LivenessStepBuilder()
    .setDirectionTextToSpeech(
        center: "Look straight ahead while keeping your face in the center of the frame.",
        right: "Turn your face to the right.",
        left: "Turn your face to the left.",
        up: "Look up.",
        down: "Look down."
    )
    .setIdentifyTimeout(35)
    .setTitle("Liveness Check")
    .setInfoView(faceInfo)
    .setStepInformationTextToSpeech("Look at the camera and place your face inside the frame. Move your head according to the directions.")
    .setIsGlareDetectionEnable(true)
    .setTooBrightText("The environment is too bright. Please reduce the light.")
    .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
    .build()

VideoCall Step Usage

let videoCall = StepBuilder()
    .setIdentifyTimeout(35)
    .setTitle("Video Call")
    .setInfoView(videoCallInfo)
    .setStepType(.videoCall)
    .setStepInformationTextToSpeech("The video call is starting. Make sure there is sufficient lighting.")
    .build()

LivenessConfig

Used to customize the instructions shown during the liveness step.

LivenessConfig Properties

Parameter	Type	Description
dotRadius	CGFloat?	Specifies the radius of the dots displayed during the liveness check.
dotColor	UIColor?	Defines the default color of the dots used for liveness indicators.
activeDotColor	UIColor?	Sets the color of the currently active dot during the liveness check.
titleText	String?	The main title text displayed during the liveness check.
upText	String?	The instruction shown when the user needs to move their head upward.
downText	String?	The instruction shown when the user needs to move their head downward.
leftText	String?	The instruction shown when the user needs to turn their head to the left.
rightText	String?	The instruction shown when the user needs to turn their head to the right.
centerYourFaceText	String?	The instruction asking the user to center their face within the frame.
faceNotDetectedText	String?	The message shown when the user's face cannot be detected during the liveness check.

LivenessConfig Usage

let livenessConfig = LivenessConfig(
    dotRadius: 10.0,
    dotColor: .gray,
    activeDotColor: .green,
    titleText: "Face Verification",
    upText: "Please raise your head",
    downText: "Please lower your head",
    leftText: "Please turn your head to the left",
    rightText: "Please turn your head to the right",
    centerYourFaceText: "Please center your face",
    faceNotDetectedText: "Face not detected"
)

UIConfig

Used to define the general design properties used in Info screens and bottom sheets.

UIConfig Properties

Parameter	Type	Description
buttonColor	UIColor?	Specifies the background color of buttons displayed on Info screens and bottom sheets.
buttonTextColor	UIColor?	Sets the text color of buttons displayed on Info screens and bottom sheets.
bulletTextColor	UIColor?	Defines the color of bullet-point text used on Info screens and bottom sheets.
buttonCornerRadius	Int?	Specifies the corner radius of buttons for styling purposes.
bulletIconName	String?	Specifies the name of the icon used for bullet points on Info screens and bottom sheets.

UIConfig Usage

let uiConfig = UIConfig(
    buttonColor: UIColor(named: "purple_700"),
    buttonTextColor: .white,
    bulletTextColor: UIColor(named: "teal_700"),
    buttonCornerRadius: 30,
    bulletIconName: "bullet_icon"
)

KYCManagerConfig

Used to configure general UI information and error messages.

KYCManagerConfig Properties

Parameter	Type	Description
showCompletedScreen	Bool	Controls whether the screen shown after a successful completion is enabled or disabled. Default is false.
cameraErrorMessage	[String]	Allows customization of messages used for camera errors.
nfcErrorMessage	[String]	Allows customization of messages used for NFC errors.
videoCallErrorMessage	[String]	Allows customization of messages used for video call errors.
timeOutErrorMessage	[String]	Allows customization of messages used for timeout errors.
serverErrorMessage	[String]	Allows customization of messages used for server errors.
rejectedErrorMessage	[String]	Allows customization of messages used for rejection errors.
identityReadFailedError	[String]	Allows customization of messages used for identity reading errors.
videoCallSplashScreenAssetName	String	Used to customize the full-screen image displayed when the video call screen opens.
closeIconAssetName	String	Used to customize the image used for the close button on Info screens.
livenessConfig	LivenessConfig	Used to customize the instructions for the liveness step.
uiConfig	UIConfig?	Used to customize the instructions shown on the Info screen and bottom sheet.
ttsConfig	TTSConfig	Used to customize the text-to-speech feature.
videoCallExternalLogoImage	UIImage	Used to customize the logo displayed when the video call screen opens.

KYCManagerConfig Usage

let configuration = KYCManagerConfigBuilder()
    .setCameraErrorMessage([.cameraPermissionDenied: "Camera permission denied"])
    .setNFCErrorMessage([.deviceNotHaveNFC: "Your device does not support NFC"])
    .setShowCompletedScreen(true)
    .setVideoCallSplashScreenAssetName("splash_background")
    .setCloseIconAssetName("close_icon")
    .setLivenessConfig(livenessConfig)
    .setUIConfig(uiConfig)
    .setTTSConfig(TTSConfig(isEnabled: true, speechRate: 0.5, language: "tr-TR"))
    .setVideoCallExternalLogoImage(UIImage(named: "your_logo") ?? UIImage())
    .build()

KYCManagerDelegate

The delegate protocol used to handle events and errors during the KYC process.

import KYCFramework

class ViewController: UIViewController, KYCManagerDelegate {

    func onCompletion(_ isSuccess: Bool) {
        // You can listen to whether the identity verification step succeeded through this function.
        if isSuccess {
            print("The KYC process was completed successfully")
        } else {
            print("The KYC process failed")
        }
    }

    // The onEvent and onError functions let you handle which steps are opened,
    // which operations are performed, and any error states that occur during the identity verification flow.
    // These functions provide the required information for logging to platforms such as Countly and Firebase.

    func onEvent(_ event: KYCFramework.LogState) {
        print("KYC Event: \(event)")
    }

    func onError(_ error: KYCFramework.KYCError) {
        print("KYC Error: \(error)")
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        KYCManager.shared.delegate = self
    }
}

Starting KYC

Start Function

func startKYC(token: String) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }

        KYCManager.shared.enterKYC(
            from: self.navigationController!,
            clientToken: token,
            applicationId: applicationId,
            stepList: KYCConfig.getStepList(),
            configuration: KYCConfig.getManagerConfig()
        )
    }
}

Full Configuration Example

class KYCConfig {

    // Info template
    static let infoTemplate = InfoBuilder()

    // Front Info
    static let frontInfo = infoTemplate
        .setTitleText("ID Card Front Side")
        .setDescriptionText("We will scan the front side of your ID card")
        .setButtonText("Start")
        .setLottieFileName("id_front_animation")
        .setBullets([
            "Place your ID card on a flat surface",
            "Make sure the ID information is clearly visible"
        ])
        .build()

    // Back Info
    static let backInfo = infoTemplate
        .setTitleText("ID Card Back Side")
        .setDescriptionText("We will scan the back side of your ID card")
        .setButtonText("Continue")
        .setLottieFileName("id_back_animation")
        .setBullets([
            "Turn your ID card over",
            "Make sure the MRZ code is clearly visible"
        ])
        .build()

    // Step template
    static let stepTemplate = StepBuilder()

    // Steps
    static let idFrontStep = stepTemplate
        .setIdentifyTimeout(35)
        .setTitle("ID Card Front Side")
        .setInfoView(frontInfo)
        .setStepType(.idcardFront)
        .setStepInformationTextToSpeech("Hold the front side of your ID card parallel to the phone screen. The ID card must be positioned fully inside the frame.")
        .setIsGlareDetectionEnable(true)
        .setGlareDetectedText("There is light reflection. Please hold the document at a different angle.")
        .setTooBrightText("The environment is too bright. Please reduce the light.")
        .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
        .setMultipleDocumentsDetectedText("Please show only one document.")
        .build()

    static let idBackStep = stepTemplate
        .setIdentifyTimeout(35)
        .setTitle("Back Side")
        .setInfoView(backInfo)
        .setStepType(.idcardBack)
        .setStepInformationTextToSpeech("Hold the back side of your ID card parallel to the phone screen. Make sure all information is clearly visible.")
        .setIsGlareDetectionEnable(true)
        .setGlareDetectedText("There is light reflection. Please hold the document at a different angle.")
        .setTooBrightText("The environment is too bright. Please reduce the light.")
        .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
        .setMultipleDocumentsDetectedText("Please show only one document.")
        .build()

    static let hologramStep = stepTemplate
        .setIdentifyTimeout(35)
        .setTitle("Hologram")
        .setInfoView(hologramInfo)
        .setStepType(.hologram)
        .setStepInformationTextToSpeech("Scan the hologram label on your ID card. The hologram should appear bright and clear.")
        .build()

    static let nfcStep = stepTemplate
        .setIdentifyTimeout(35)
        .setTitle("NFC")
        .setInfoView(nfcInfo)
        .setStepType(.nfc)
        .setStepInformationTextToSpeech("Move your ID card close to the back of your phone. Make sure the NFC feature is enabled.")
        .build()

    static let faceStep = livenessStepTemplate
        .setDirectionTextToSpeech(
            center: "Look straight ahead while keeping your face in the center of the frame.",
            right: "Turn your face to the right.",
            left: "Turn your face to the left.",
            up: "Look up.",
            down: "Look down."
        )
        .setIdentifyTimeout(35)
        .setTitle("Liveness Check")
        .setInfoView(faceInfo)
        .setStepInformationTextToSpeech("Look at the camera and place your face inside the frame. Move your head according to the directions.")
        .setIsGlareDetectionEnable(true)
        .setTooBrightText("The environment is too bright. Please reduce the light.")
        .setTooDarkText("The environment is too dark. Please move to a brighter environment.")
        .build()

    static let videoCall = stepTemplate
        .setIdentifyTimeout(35)
        .setTitle("Video Call")
        .setInfoView(videoCallInfo)
        .setStepType(.videoCall)
        .setStepInformationTextToSpeech("The video call is starting. Make sure there is sufficient lighting.")
        .build()

    // Configuration
    static let configuration = KYCManagerConfigBuilder()
        .setCameraErrorMessage([
            .cameraPermissionDenied: "Camera permission was not granted. Please enable camera access in settings.",
            .cameraSourceNotFound: "Camera not found."
        ])
        .setNFCErrorMessage([
            .deviceNotHaveNFC: "Your device does not support NFC.",
            .notEnable: "NFC is disabled. Please enable NFC in settings."
        ])
        .setShowCompletedScreen(true)
        .setTTSConfig(TTSConfig(isEnabled: true, speechRate: 0.5, language: "en-US"))
        .setVideoCallExternalLogoImage(UIImage(named: "your_logo") ?? UIImage())
        .build()

    // Helper functions
    static func getStepList() -> [Step] {
        return [idFrontStep, idBackStep, hologramStep, nfcStep, faceStep, videoCall]
    }

    static func getManagerConfig() -> KYCManagerConfig {
        return configuration
    }
}

Error Handling

The types and descriptions of errors that may be returned by the SDK are listed below. These error messages can be customized inside KYCManagerConfig.

Camera Errors

• cameraPermissionDenied: Camera permission denied
• cameraSourceNotFound: Camera not found
• flashMode: Flash toggle error

NFC Errors

• deviceNotHaveNFC: Device does not support NFC
• notEnable: NFC is not enabled
• tagNotSupported: ID card is not supported
• tagLost: The ID card was lost during reading

Video Call Errors

• connectionFailed: Connection error
• microphonePermissionDenied: Microphone permission denied

Other Errors

• timeout: Timeout error
• serverError: Server error
• rejected: Process rejected
• identityReadFailed: Failed to read the ID card