Skip to main content
Version: 1.6.0

Teydex Android Document

This document contains all the necessary steps, usage examples, and platform-specific technical details for securely and smoothly integrating the Teydex library into the Android platform.

Version Requirements

To use the Teydex Android library smoothly, you need to check your versions.

PlatformMin version
AndroidminSdkVersion: 24
compileSdkVersion: 34
targetSdkVersion: 34
kotlinVersion: 1.8.0

Android Gradle Configuration

You need to add the following configuration along with the GitLab token in the repository definitions under Settings.gradle. Ensure that you enter the necessary credentials for repository access correctly.

{
maven {
isAllowInsecureProtocol = true
name = "GitLab"
url = uri("<REPO_URL>")
credentials(HttpHeaderCredentials::class) {
name = "Private-Token"
value = "GITLAB_TOKEN"
}
authentication {
create<HttpHeaderAuthentication>("header")
}
}
  • REPO_URL should be replaced with the URL provided to you.
  • Replace the PRIVATE_TOKEN field with the personal access token provided by your organization.
  • The allowInsecureProtocol = true setting should only be used in secure networks or on internal private servers.

Gradle Configuration

Add the following lines to your android/app/build.gradle file:

implementation("com.innovance:kyc:1.6.0")

The following dependencies must be defined at the minimum specified versions in your project's android/build.gradle file. Using lower versions may result in compilation or runtime errors related to the library.

buildscript {
dependencies {
classpath("com.android.tools.build:gradle:7.4.2") // Minimum supported version: 7.4.2
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0" // Minimum supported version: 1.8.0
}
}

Info Screen

The Info screen in your KYC application refers to the informational pages displayed before the steps. Optionally, the following parameters can be added for each step.

Info Screen Features

ParameterTypeDescription
toolbarTitleStringSpecifies the text for the toolbar.
titleTextStringSpecifies the text for the title.
descriptionTextStringSpecifies the text for the description.
buttonTextStringSpecifies the text for the button that starts the step.
imageResId@RawRes IntSpecifies the image to be used.
lottieResId@RawRes IntSpecifies the Lottie animation.
bulletsList<String>Information about the next step can be presented in bullet points.
bulletIcon@RawRes IntSpecifies the icon for the bullet points.

Info Screen Usage

Below is an example of how to use the Info screen.


val frontInfo = buildInfo {
toolbarTitle("Kimlik Ön Yüz")
descriptionText("Lütfen aşağıdaki adımları dikkatlice takip ediniz:")
buttonText("Devam")
lottieResId(R.raw.front)
bullets(
listOf(
"Kimliğinizi Yerleştirin\n" +
"Kimliğinizin arka yüzünü, telefon ekranına paralel bir şekilde
tutun. Kimlik, ekranda görünen şablonun içine tam olarak yerleşecek
şekilde konumlandırılmalıdır.",
"Kimlik Bilgilerinin Görünürlüğü\n Kimlik üzerindeki tüm
bilgilerin net bir şekilde göründüğünden emin olun. Kimlik bilgileri
bulanık olmamalı ve kolayca okunabilir olmalıdır")
)
}

Step

The features to be used in all steps are specified in this section. These features are available in every step (Front, Back, Hologram, NFC, Liveness, Passport, VideoCall, Selfie, VideoRecord).

Step Features

ParameterTypeDescription
addInfoInfoUsed to add an Info screen to the corresponding step. It is optional.
toolbarTitleStringRepresents the text for the Toolbar to be displayed in the corresponding step.
toolbarRightCloseIconStringRepresents the exit icon to terminate the corresponding step.
toolbarLeftCloseIconStringRepresents the exit icon to terminate the corresponding step.
identifyTimeoutLongSpecifies the timeout duration for the corresponding step (ms). e.g., 10_000
stepInformationTextToSpeechStringSpecifies the voice guidance message.

Glare Detection

Starting with v1.1.0, 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:

ParameterTypeDescription
isGlareDetectionEnableBooleanEnables glare detection for the corresponding step. Default is true for Front and Back, and false for Passport.
glareDetectedTextStringWarning text shown when a glare is detected on the document.
tooBrightTextStringWarning text shown when the environment is too bright.
tooDarkTextStringWarning text shown when the environment is too dark.
multipleDocumentsDetectedTextStringWarning text shown when multiple documents are detected in the camera frame.

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

ParameterTypeDescription
isGlareDetectionEnableBooleanEnables ambient light monitoring in the Liveness step. Default is true.
tooBrightTextStringWarning text shown when the environment is too bright.
tooDarkTextStringWarning 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).

Front Step Usage

      val front = buildFront {
identifyTimeout(30_000L)
addInfo(frontInfo)
toolbarTitle("Kimlik Ön Yüz")
toolbarRightCloseIcon(R.drawable.ic_close)
isGlareDetectionEnable(true)
glareDetectedText("Glare detected. Please hold the document at a different angle.")
tooBrightText("The environment is too bright. Please reduce the light.")
tooDarkText("The environment is too dark. Please move to a brighter area.")
multipleDocumentsDetectedText("Please show only one document.")
}

Back Step Usage

      val back = buildBack {
identifyTimeout(30_000L)
addInfo(backInfo)
toolbarTitle("Kimlik Arka Yüz")
toolbarRightCloseIcon(R.drawable.ic_close)
isGlareDetectionEnable(true)
glareDetectedText("Glare detected. Please hold the document at a different angle.")
tooBrightText("The environment is too bright. Please reduce the light.")
tooDarkText("The environment is too dark. Please move to a brighter area.")
multipleDocumentsDetectedText("Please show only one document.")
}

NFC Step Usage

     val nfc = buildNFC {
addInfo(nfcInfo)
toolbarRightCloseIcon(R.drawable.ic_close)
toolbarTitle("NFC")
}

Hologram Step Usage

     val hologram = buildHologram {
addInfo(hologramInfo)
toolbarTitle("Hologram")
}

Passport Step Usage

     val passport = buildPassport {
identifyTimeout(60_000L)
addInfo(passportInfo)
toolbarTitle("Passport")
toolbarRightCloseIcon(R.drawable.ic_close)
}

VideoCall Step Features

ParameterTypeDescription
splashScreenResourceId@DrawableRes IntUsed to define the splash screen displayed before VideoCall starts.
caution

Starting with v1.1.0, it is recommended to configure the VideoCall splash screen and external logo image via UIConfig. See the UIConfig section below.

VideoCall Step Usage

     val videoCall = buildVideoCall {
addInfo(videoCallInfo)
splashScreenResourceId(R.drawable.bg_splash)
}

Liveness Step Features

ParameterTypeDescription
rightTextStringThe command telling the user to look right for the liveness photo.
leftTextStringThe command telling the user to look left for the liveness photo.
upTextStringThe command telling the user to look up for the liveness photo.
downTextStringThe command telling the user to look down for the liveness photo.
centerYourFaceTextStringThe command telling the user to look directly (straight) at the camera for the liveness photo.
multipleFaceTextStringThe message informing the user when multiple faces are detected during the liveness step.
dotColor@ColorInt IntThe color of the dots indicating a completed command during the liveness step.
dotRadiusIntThe size (radius) of the dots indicating a completed command during the liveness step.
rightTextToSpeechStringThe voice command telling the user to look right for the liveness photo.
leftTextToSpeechStringThe voice command telling the user to look left for the liveness photo.
upTextToSpeechStringThe voice command telling the user to look up for the liveness photo.
downTextToSpeechStringThe voice command telling the user to look down for the liveness photo.
centerTextToSpeechStringThe voice command telling the user to look directly (straight) at the camera for the liveness photo.

Liveness Step Usage

    val liveness = buildLiveness {
dotColor(Color.Green.toArgb())
rightText("yüzünüzü sağa çeviriniz")
leftText("sola çeviriniz")
upText("yüzünüzü yukarı kaldırınız")
downText("aşağı yöne bakınız")
multipleFaceText("birden fazla yüz algılandı")
identifyTimeout(60_000)
addInfo(livenessInfo)
toolbarTitle("Liveness")
isGlareDetectionEnable(true)
tooBrightText("The environment is too bright. Please reduce the light.")
tooDarkText("The environment is too dark. Please move to a brighter area.")
}

Selfie Step Features

Added in v1.6.0. A step where the user verifies themselves by taking a selfie photo.

ParameterTypeDescription
identifyTimeoutLongTimeout for the step (ms). (Default: 30_000)
centerYourFaceTextStringText telling the user to center their face in the frame.
tooCloseTextStringWarning text shown when the face is too close to the camera.
tooFarTextStringWarning text shown when the face is too far from the camera.
captureButtonTextStringLabel of the capture button.
retakeButtonTextStringLabel of the retake button.
confirmButtonTextStringLabel of the button confirming the captured photo.

Selfie Step Usage

    val selfie = buildSelfie {
identifyTimeout(15_000L)
centerYourFaceText("Center your face in the frame")
tooCloseText("Move your face away")
tooFarText("Move your face closer")
captureButtonText("Take Photo")
retakeButtonText("Retake")
confirmButtonText("Confirm")
addInfo(selfieInfo)
toolbarTitle("Selfie")
toolbarRightCloseIcon(R.drawable.ic_close)
stepInformationTextToSpeech("Center your face in the frame and press the capture button.")
}

VideoRecord Step Features

Added in v1.6.0. A spoken video verification step where the user creates a video recording by reading the text shown on the screen aloud.

note

The text the user must read aloud during the VideoRecord step (prompt_text) is provided to the SDK by the backend. The text is sent to the backend in the transaction init request inside the options object via the video_record_prompt_text and video_record_prompt_mandatory_texts fields; the backend returns it to the SDK during the video step and scores the reading accuracy against these texts.

ParameterTypeDescription
identifyTimeoutLongTimeout for the step (ms). (Default: 60_000)
faceCenterTimeoutMsLongTimeout for centering the face before recording (ms). (Default: 15_000)
readyCountdownMsLongCountdown shown before the recording starts (ms). (Default: 3_000)
recordingDurationMsLongMaximum video recording duration (ms). (Default: 20_000)
videoQualityVideoRecordQualityRecording quality: LOW, MEDIUM, HIGH. (Default: MEDIUM)
centerYourFaceTextStringText telling the user to center their face in the frame.
tooCloseTextStringWarning text shown when the face is too close to the camera.
tooFarTextStringWarning text shown when the face is too far from the camera.
moveLeftTextStringText telling the user to move their face to the left.
moveRightTextStringText telling the user to move their face to the right.
moveUpTextStringText telling the user to move their face up.
moveDownTextStringText telling the user to move their face down.
lookStraightTextStringText telling the user to look straight at the camera.
headTiltedTextStringWarning text shown when the user's head is tilted.
startButtonTextStringLabel of the start-recording button.
stopButtonTextStringLabel of the stop-recording button.
retakeButtonTextStringLabel of the re-record button.
confirmButtonTextStringLabel of the button confirming and submitting the recording.
readingInstructionTextStringInstruction text stating that the prompt must be read aloud during the recording.

VideoRecord Step Usage

    val videoRecord = buildVideoRecord {
identifyTimeout(60_000L)
faceCenterTimeoutMs(15_000L)
readyCountdownMs(3_000L)
recordingDurationMs(20_000L)
videoQuality(VideoRecordQuality.MEDIUM)
centerYourFaceText("Center your face in the frame")
tooCloseText("Move your face away")
tooFarText("Move your face closer")
moveLeftText("Move your face to the left")
moveRightText("Move your face to the right")
moveUpText("Move your face up")
moveDownText("Move your face down")
lookStraightText("Look straight at the camera")
headTiltedText("Straighten your head")
startButtonText("Start Recording")
stopButtonText("Stop Recording")
retakeButtonText("Record Again")
confirmButtonText("Confirm and Submit")
readingInstructionText("Read the text shown on the screen aloud")
addInfo(videoRecordInfo)
toolbarTitle("Spoken Video Verification")
toolbarRightCloseIcon(R.drawable.ic_close)
stepInformationTextToSpeech("Create a video recording by reading the text shown on the screen aloud.")
}

UIConfig

Used to define the general design features to be used in the application. As of v1.4.5, UIConfig has a modular structure that configures color, typography, and shape settings under separate sub-blocks (colors, typography, shapes). Any setter that is omitted falls back to the SDK's default, so the configuration is purely additive. As of v1.6.0, the full color and shape setter surface is exposed.

colors

ParameterTypeDescription
primaryColor@ColorInt IntPrimary brand color (MaterialTheme.colorScheme.primary, outline button border).
onPrimaryColor@ColorInt IntContent color rendered on top of primaryColor.
surfaceColor@ColorInt IntSurface color (bottom sheets, cards).
onSurfaceColor@ColorInt IntContent color rendered on top of surfaceColor.
backgroundColor@ColorInt IntWindow background color.
errorColor@ColorInt IntError accent color.
successColor@ColorInt IntSuccess accent color.
textPrimaryColor@ColorInt IntPrimary text color.
textSecondaryColor@ColorInt IntSecondary text color.
overlayColor@ColorInt IntCamera overlay color — the semi-transparent area outside the document/face frame.
buttonColor@ColorInt IntBackground fill color of buttons. (Default: 0xFF1643E4)
buttonTextColor@ColorInt IntText/content color of buttons. (Default: white)
lineButtonTextColor@ColorInt IntText color of outlined (line) buttons. (Default: black)
bulletTextColor@ColorInt IntText color of bullet points on info screens. (Default: 0xFF808080)
titleColor@ColorInt IntTitle text color on info screens.
descriptionColor@ColorInt IntDescription text color on info screens.
note

buttonColor/buttonTextColor/bulletTextColor are kept independent from primaryColor/onPrimaryColor/textSecondaryColor for backwards compatibility. To apply a single brand color, set both members of each pair.

typography

ParameterTypeDescription
fontFamily@FontRes IntFont family used across the SDK (R.font.<file>). If unset, the system font is used.
titleFontSizeInt (sp)Font size for titles. (Default: 28)
bodyFontSizeInt (sp)Font size for body text. (Default: 16)
labelFontSizeInt (sp)Font size for small labels (bullets, camera warnings). (Default: 14)
timerFontSizeInt (sp)Font size for the countdown text on liveness/timer screens. (Default: 32)
buttonFontSizeInt (sp)Font size for button labels. (Default: 16)
titleFontWeightIntFont weight for title text (100–900). (Default: 700)
bodyFontWeightIntFont weight for body/label text. (Default: 400)

shapes

ParameterTypeDescription
buttonCornerRadiusInt (dp)Corner radius of buttons. (Default: 12)
cardCornerRadiusInt (dp)Corner radius of warning cards / hint boxes. (Default: 8)
imageFrameCornerRadiusInt (dp)Corner radius of image / animation frames. (Default: 18)
bottomSheetCornerRadiusInt (dp)Corner radius of bottom sheet top edges. (Default: 28)
cameraOverlayCornerRadiusInt (dp)Corner radius of the camera overlay cutout. (Default: 12)

VideoCall images (root level)

ParameterTypeDescription
setVideoCallExternalLogoImage@DrawableRes IntAdded in v1.1.0. Specifies the external logo image to be displayed on the VideoCall screen.
setVideoCallSplashScreenImage@DrawableRes IntAdded in v1.1.0. Specifies the splash screen image displayed before VideoCall starts.

UIConfig Usage

    val uiConfig = buildUIConfig {
colors {
primaryColor(0xFF1643E4.toInt())
buttonColor(0xFF1643E4.toInt())
buttonTextColor(0xFFFFFFFF.toInt())
bulletTextColor(0xFF808080.toInt())
lineButtonTextColor(0xFF000000.toInt())
surfaceColor(0xFFFFFFFF.toInt())
overlayColor(0x80141414.toInt())
}
typography {
fontFamily(R.font.brand_regular)
titleFontSize(28)
buttonFontSize(16)
}
shapes {
buttonCornerRadius(30)
bottomSheetCornerRadius(28)
}
setVideoCallExternalLogoImage(R.drawable.ic_logo_sample)
setVideoCallSplashScreenImage(R.drawable.ic_logo_sample)
}

KYC

This is the main function that will start the KYC process. All specified features are added here, and a KYC flow is initiated with the process function.

KYC Features

ParameterTypeDescription
baseUrlStringThe baseUrl to be used globally in the application, the URL from the on-premise server.
videoCallBaseUrlStringThe URL to be used for the VideoCall flow, the URL from the on-premise video call server.
addUIConfigUIConfigUsed to specify UI configuration features globally across the SDK.
showCompletedScreenBooleanSpecifies whether to display the success screen when all steps are successfully completed.
completedScreenTextsCompletedScreenTextsAdded in v1.6.0. Used to customize the title, description and button text of the success screen.
languageStringAdded in v1.6.0. Sets the SDK language ("tr", "en", "ru"). Falls back to the device language when unset.
identifierStepsMutableList<Step>Ensures all steps are included in the system with the created features.
addClientTokenStringUsed to pass the client token required to initialize the SDK.
addApplicationIdStringUsed to pass the applicationId required to initialize the SDK.
addErrorMessagesHashMap<KYCErrorString>Used to display custom error messages in the SDK.
onEventKYCEventCan be used to forward events from the SDK to third-party analytics tools like Firebase, Mixpanel, or Countly.
onErrorKYCErrorCan be used to log error messages generated by the SDK.
onCompletionBooleanDeprecated; use onProcessFinished instead. Will be removed entirely in the next major version; still called for backward compatibility for now.
onProcessFinishedKYCProcessResultNotifies the host app when the KYC flow finishes as successful, failed, or cancelled.
shouldGetCustomerLocationBooleanSpecifies whether the user's location information should be collected.
sslPinsList<String>Used to add the necessary sha256 keys for SSL pinning.
processContextUsed to initialize the SDK for a KYC flow with the specified features.
dismissKYCBooleanUsed to stop and close the active KYC flow programmatically.

KYC Usage

    val kyc = buildKYC {
addUIConfig(uiConfig)
showCompletedScreen(true)
completedScreenTexts(CompletedScreenTexts.buildCompletedScreenTexts {
titleText("Your account is verified!")
descriptionText("You can now continue using the app.")
buttonText("Continue")
})
language("en")
identifierSteps(mutableListOf(front,hologram,back,nfc,liveness,passport,videoCall,selfie,videoRecord))
addClientToken(AppSharedPref.getClientToken(context))
addApplicationId(AppSharedPref.getAppId(context))
addErrorMessages(hashMapOf(
KYCNFCError.NOT_ENABLE to "not enable",
KYCCameraError.FLASH_MODE to " flash mode"))
onEvent { Log.i("TEST_LOG", "KYC Event:${it.name}")}
onError { Log.i("TEST_LOG", "KYC Error:${it.type} - ${it.message}")}
onProcessFinished { result ->
when (result) {
KYCProcessResult.Successful -> Log.i("TEST_LOG", "KYC Successful")
is KYCProcessResult.Failed -> Log.i("TEST_LOG", "KYC Failed step:${result.stepName} reason:${result.reason}")
is KYCProcessResult.Cancelled -> Log.i("TEST_LOG", "KYC Cancelled step:${result.stepName} reason:${result.reason}")
}
}}
kyc.process(context)
kyc.dismissKYC()
note

KYCProcessResult.Failed and KYCProcessResult.Cancelled also carry a reason field alongside stepName (Failed.reason: String, Cancelled.reason: KYCCancelReason). This field holds the actual reason the flow failed or was cancelled; it's recommended to log result.reason as well for diagnostics and support.

KYCError

The type and descriptions of errors that may come from the SDK can be accessed here. Error messages that need to be changed can be modified using addErrorMessages in the form of KYCError,String. For example: KYCCameraError.FLASH_MODE to "flash mode".

ParameterDescription
UNKNOWNBilinmeyen hata
FIRST_STEP_UNDEFINEDİlk adım null olamaz!
APP_IDENTIFIER_STEPS_IS_NOT_SAME_APIUygulamada tanımladığınız adımlar ile API'de tanımladığınız adımların aynı olması gerekmektedir.

KYCCameraError

ParameterDescription
UNKNOWNBilinmeyen bir hata oluştu. Lütfen tekrar deneyin.
PERMISSION_NOT_GRANTEDKamera izinleri verilmedi. Lütfen kamera izinlerinizi veriniz.
CAMERA_PERMISSION_REQUIREDKamera izni gerekli. Lütfen kamera izni veriniz.
CAMERA_PERMISSION_PERMANENTLY_DENIEDKamera izni kalıcı olarak reddedildi. Lütfen ayarlardan kamera izni veriniz.
RECORD_AUDIO_REQUIREDSes kaydı izni gerekli. Lütfen ses kaydı izni veriniz.
RECORD_AUDIO_PERMANENTLY_DENIEDSes kaydı izni kalıcı olarak reddedildi. Lütfen ayarlardan ses kaydı izni veriniz.
CAMERA_SOURCE_PREVIEW_NOT_FOUNDKamera ön izlemesi oluşturulamadı. Lütfen tekrar deneyin.
CAMERA_SOURCE_NOT_FOUNDKamera bulunamadı. Lütfen kamerayı kontrol edin.
FLASH_MODEFlash aç/kapa işlemi sırasında bir hata oluştu. Lütfen tekrar deneyin.
VIDEO_WRITE_FAILEDVideo kaydedilirken bir hata oluştu. Lütfen tekrar deneyin.
VIDEO_READ_FAILEDVideo bulunamadı. Lütfen dosyanın varlığını kontrol edin.
VIDEO_EXECUTE_COMMAND_CANCELLED_BY_USERVideo düzenleme işlemi kullanıcı tarafından iptal edildi.
VIDEO_EXECUTE_COMMANDS_FAILEDVideo düzenleme işlemi başarısız oldu. Lütfen tekrar deneyin.
VIDEO_COMPRESS_FAILEDVideo sıkıştırma işlemi başarısız oldu. Lütfen tekrar deneyin.
CODEC_NOT_SUPPORTEDVideo düzenleme işlemi başarısız oldu. Lütfen tekrar deneyin.

KYCNFCError

ParameterDescription
UNKNOWNBilinmeyen bir hata oluştu. Lütfen tekrar deneyin.
DEVICE_NOT_HAVE_NFCCihazda NFC modülü bulunmuyor. Bu özellik yalnızca NFC destekli cihazlarda çalışır.
DISABLE_NFC_ADAPTERNFC modülü devre dışı bırakılırken bir hata oluştu. Lütfen NFC'yi tekrar etkinleştirin.
NOT_ENABLENFC modülü aktif değil. Lütfen NFC'yi etkinleştirin.
NOT_DISCOVEREDNFC açıkken kimlik taranamadı. Lütfen kimliği tekrar yaklaştırın.
TAG_NOT_SUPPORTEDKimlik bilgisi desteklenmiyor. Bu kimlik kartı desteklenmemektedir.
TAG_LOSTKimlik bilgisi okunamadı. Lütfen kimliği tekrar yaklaştırın.
ISODEP_NOT_FOUNDKimlik bilgisi okunamadı. Lütfen kimliği tekrar yaklaştırın.
PASSIVE_AUTH_FAILEDKimlik bilgisi algılanamadı. Lütfen geçerli bir kimlik kullanın.
PHOTO_NOT_FOUNDKimlik kartında fotoğraf bilgisi yok. Lütfen geçerli bir kimlik kullanın.
PERSON_DETAIL_NOT_FOUNDKişi bilgisine ihtiyaç var. Lütfen kimliği doğru yerleştirin.
CARD_AUTH_FAILEDKimlik bilgileri tanımlanamadı.
WRONG_MRZ_STRINGMRZ bilgisi algılanamadı. Lütfen kimliği tekrar yaklaştırın.