Getting Started with the SDK

About CafSDK

This technical documentation covers the implementation of CafSDK for Android, detailing the configuration, initialization, execution of capture flows, and advanced customizations.

Currently, CafSDK integrates 2 main modules: Face Liveness (FL) and Document Detector (DD), executed sequentially with a unified configuration interface.

What is Face Liveness

It is the module that validates the authenticity of a face captured by a camera, ensuring that the image corresponds to a real person.

Technical characteristics:

• URL configuration for authentication (authBaseUrl) and liveness verification (livenessBaseUrl).

• Reverse proxy endpoints and security certificates (optional).

• Flags to enable screen capture and debug mode.

• Support for multiple authentication providers.

Whats is Document Detector

It is the module that enables the capture and processing of documents (e.g., ID card, social security card, passport, etc.).

Technical characteristics:

• Configuration of a step-by-step flow defined by DocumentDetectorStep for document capture.

• Operational parameters, such as timeout, manual capture flags, and other settings.

• Possibility of using the camera for framing validations, or document file upload.

---

Get started with the SDK

Add the dependency

For your Android project to utilize CafSDK, it is necessary to correctly configure the Maven repositories and declare the SDK dependencies in your project. This step ensures that the artifacts (libraries) are downloaded and integrated during the build.

Requirements for adding

For Face Liveness

The minimum requirements for the Caf Face Liveness module include:

Requirement	Version
Android SDK API - minimum version (minSdk)	26
Android SDK API - compile version (compileSDK)	34
Kotlin	1.9.10
Gradle	8.4
Android Gradle Plugin (AGP)	8.3.2

versionName e versionCode are mandatory for the correct functioning of the SDK.

For Document Detector

The minimum requirements for the Caf Document Detector module include:

Requirement	Version
Android SDK API - minimum version (minSdk)	26
Android SDK API - compile version (compileSDK)	34
Kotlin	1.9.10
Gradle	8.4
Android Gradle Plugin (AGP)	8.3.2

Step-by-step to add

Step 1 - Add the Maven repository

In this step, you need to inform Gradle where to locate the CafSDK artifacts and additional dependencies that may be used (such as those related to Caf Face Liveness, DocumentDetector or FingerPrintJS).

To do this, configure the project's settings.gradle.kts file (usually located at the root level), including the following repositories:

• Caf Repository: where the CafSDK artifacts are hosted.

• iProov Repository: required if you are using the CafFaceLiveness module, which depends on iProov artifacts for secure processing.

• FingerPrintJS Repository: internal dependency of the modules.

• JitPack: for dependencies hosted via JitPack (Github).

Configuration example:

repositories {
    // Caf Repository
    maven { url = uri("https://repo.combateafraude.com/android/release") }
    
    // iProov Repository
    maven { url = uri("https://raw.githubusercontent.com/iProov/android/master/maven/") }
    
    // FingerPrintJS Repository
    maven { setUrl("https://maven.fpregistry.io/releases") }
    
    // JitPack
    maven { setUrl("https://jitpack.io") }
}

More details

• Flexibility: this configuration allows the project to download all necessary dependencies from different sources, ensuring compatibility and updated versions.

• Maintenance: if there are updates to the repositories or changes in the publication structure, simply update this section to reflect the new URLs.

• Context: the inclusion of repositories is done only once at the project level, ensuring that all modules can access the necessary artifacts.

Step 2 - Include the CafSDK dependency

After configuring the repositories, it is necessary to declare the specific CafSDK dependencies in the build.gradle.kts file of your application module. This step declares which SDK modules will be used, allowing Gradle to manage versions and resolve dependencies correctly.

Declaration of dependencies example:

dependencies {
    implementation(platform("io.caf.sdk:caf-sdk-bom:2.0.0"))
    
    // If you use Protobuf JavaLite, you should add that instead of the above dependency
    implementation("io.caf.sdk:caffaceliveness-lite") // or "io.caf.sdk:caffaceliveness-ui-lite" if you want a customized interface.
    // If you use Protobuf Java, you should add the following dependency
    // implementation("io.caf.sdk:caffaceliveness-core") // or "io.caf.sdk:caffaceliveness-ui-core" if you want a customized interface.
    
    // Dependência do módulo Document Detector:
    implementation("io.caf.sdk:document-detector") // or "io.caf.sdk:document-detector-ui" if you want a customized interface.
}

Important

Caf BoM (Bill of Materials)

Using the BoM helps centralize the version management of all CafSDK modules. Thus, all SDK-related dependencies will use the same defined version, avoiding conflicts and facilitating updates.

Capture Modules

• Caf Face Liveness: choose the appropriate dependency, according to the Java type your application uses (Protobuf Java or JavaLite).

  • The "Lite" version is optimized for performance and size. It also internally uses the JavaLite Protobuf version.

  • The "Core" version may offer additional functionalities or compatibility with other resources, as it uses Protobuf Java (full version).

  • It is also possible to choose between the standard version or the version that contains Caf's graphical interfaces (indicated by the -ui suffix), according to the user experience customization needs.

• Caf Document Detector:

  • It is also possible to choose between the standard version or the version that contains Caf's graphical interfaces (indicated by the -ui suffix), according to the user experience customization needs.

Version Verification

Always check the latest version of CafSDK on the release notes to ensure you are using the most up-to-date and compatible versions.

This configuration ensures that your project is prepared to integrate CafSDK, ensuring that all necessary artifacts are located and incorporated during the build. If there are any changes to the repositories or new dependencies are introduced, update the settings.

---

How to initialize the SDK

Permissions

For the modules to operate correctly, some permissions need to be declared in the AndroidManifest.xml file, check:

For Face Liveness

Permission	Description	Necessity
android.permission.CAMERA	Allows access to the camera to capture images and perform face verification (liveness).	Mandatory
android.permission.INTERNET	Allows communication with authentication and verification services (HTTPS/WSS).	Mandatory

For Document Detector

Permission	Description	Necessity
android.permission.CAMERA	Allows access to the camera to capture document images.	Only for capture
android.permission.INTERNET	Allows captured images to be sent to servers for processing and validation.	Mandatory
android.permission.READ_EXTERNAL_STORAGE	Allows access to stored files and images for processing, if necessary.	Only for upload

Configurations

It is necessary to configure the SDK so that it understands the execution flow and the specific parameters of each module. The initialization process is divided into 2 parts: global configuration and module-specific configuration.

Global configuration

In this step, you create an object of type CafSdkConfiguration, which serves as a central container for all capture flow configurations.

1. Module presentation order (presentationOrder):

• Define the sequence in which the modules will be executed. This order is crucial to ensure that the capture flow follows the business logic defined by your project.

• For example, if the flow requires the document to be captured before liveness verification, the order should place the Document Detector module before Face Liveness.

• Important: depending on the implementation, there may be variations in names, such as CafModuleType.FACE_LIVENESS or CafModuleType.FACE_LIVENESS_UI, which indicate whether a version without an interface or a version with an interface will be used.

Code example for creating the global configuration:

val sdkConfiguration = CafSdkConfiguration(
    presentationOrder = listOf(
        CafModuleType.FACE_LIVENESS,     // or CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR, // or CafModuleType.DOCUMENT_DETECTOR
    ),
    waitForAllServices = true            // Optional, default is true
)

Module-specific configuration

After defining the global configurations, it is necessary to configure the modules individually. This specific configuration allows adjusting specific operational parameters, ensuring they behave according to the requirements of your capture flow.

Document Detector configuration

The Document Detector module is responsible for capturing and processing documents. Its configuration involves several parameters.

Mandatory parameter:

• Capture flow (flow):

  • Defines a list of steps (DocumentDetectorStep) that specifies which document will be captured.
  • This flow can be customized according to the types of documents to be validated by the application.

Operational parameters:

• useAdb, useDebug, and useDeveloperMode are flags that activate specific modes for testing and development, allowing greater flexibility during the integration phase.

• manualCaptureEnabled and manualCaptureTime control whether manual capture is allowed and, if so, define the time limit (in seconds) for the user to perform the action manually.

• requestTimeout defines the maximum time (in seconds) that the system will wait for a server response.

• showPopup determines whether a confirmation or instruction pop-up will be displayed to the user after document capture.

Code example for Document Detector configuration:

sdkConfiguration.setDocumentDetectorConfig(
    CafDocumentDetectorConfig(
        flow = listOf(DocumentDetectorStep(Document.RG_FRONT), DocumentDetectorStep(Document.RG_BACK)),
        useAdb = true,
        useDebug = true,
        useDeveloperMode = true,
        manualCaptureEnabled = true,
        manualCaptureTime = 45,
        requestTimeout = 60,
        showPopup = true
    )
)

Face Liveness Configuration

The Face Liveness module configuration is essential to ensure the security and reliability of the facial verification process, as it has the function of validating whether the captured face belongs to a real person. The main parameters are:

• Loading (Loading Screen):

  • The loading flag defines whether a loading screen should be displayed while the module performs processing. This improves the user experience by informing them that the process is in progress.

• Service URLs:

  • authBaseUrl and livenessBaseUrl are optional endpoints for the authentication and liveness verification services, respectively.

  • Once configured, these values must be configured with valid URLs, where authBaseUrl usually uses the HTTPS protocol for security, and livenessBaseUrl uses WSS (Secure WebSocket).

• Certificates:

  • When assigning values to service URLs, it is also necessary to provide the certificates list and ensure secure communications with trusted servers (when using reverse proxy).

• Additional Options:

  • screenCaptureEnabled enables or disables the ability to capture the screen during the verification process.

  • debugModeEnabled allows logs and additional information to be available during execution, facilitating debugging.

Code example for Face Liveness configuration:

sdkConfiguration.setFaceLivenessConfig(
    CafFaceLivenessConfig(
        loading = true,                                                         // Displays loading screen during processing
        authBaseUrl = "https://base-url.com",                                   // Optional, endpoint for authentication
        livenessBaseUrl = "wss://base-url.com",                                 // Optional, endpoint for liveness check
        certificates = listOf("4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="),  // Optional, only user with reverse proxy
        screenCaptureEnabled = true,                                            // Allows screen capture if necessary
        debugModeEnabled = true                                                 // Enable debug mode for detailed logs
    )
)

These initial configurations are fundamental to ensure that the SDK operates as expected. Each parameter was designed to offer flexibility and security, allowing the capture flow to be adapted to the specific needs of your application.

Upon completing these configurations, the SDK will be ready to be initialized and executed, ensuring robust and efficient integration with the modules.

---

Initializing the Builder

The Builder initialization is the step where the CafSDK capture flow is configured for execution. Using the CafSdkProvider.Builder class, you configure the essential parameters that define the behavior of the flow and prepare the SDK to be started.

Essential parameters

• mobileToken: token that authenticates the request and ensures that only authorized clients start the flow.

• personId: unique user identifier for which the flow will be executed.

• environment: defines the execution environment, for example, CafEnvironment.PROD for production. This enables switching between development, homologation, and production environments.

• configuration: the previously configured CafSdkConfiguration object, which contains both the execution order of the modules and the specific configurations.

• callback: a unified callback, where all events generated by the modules (such as loading, success, error, and cancellation) are handled centrally.

Detailed code example:

val sdkBuilder = CafSdkProvider.Builder(
    mobileToken = "mobile-token",        // Authentication token
    personId = "person-id",              // User identifier
    environment = CafEnvironment.PROD,   // Production environment
    configuration = sdkConfiguration,    // Global configuration with module order and parameters
    callback = ::callbackEvent           // Return of SDK events
).build()

Unified Callback

The unified callback is one of the pillars of CafSDK, responsible for notifying the application about the state of each step of the capture flow. It centralizes the events triggered by the modules and allows the developer to implement response logics, log records, and error handling.

Callback event types:

• Log: captures log messages with different levels (DEBUG, USAGE, INFO). These messages help identify the internal behavior of the flow.

• Loading: indicates the start of module processing. Useful for displaying visual progress indicators.

• Loaded: confirms that a certain action has been performed. Useful for hiding visual progress indicators.

• Success: upon successful completion, each module triggers an event containing a CafUnifiedResponse object.
• Error: if a problem occurs during execution, this event is triggered with the error message, allowing the application to handle the failure.

• Cancelled: indicates that the user or system interrupted the flow, enabling recovery actions or notifications.

Code examples:

private fun callbackEvent(event: CafUnifiedEvent): Unit = when(event) {
        is CafUnifiedEvent.Log -> {
            // Informative logs, useful for debugging and monitoring
            log("[LOG] ${event.level}: ${event.message}")
        }
        is CafUnifiedEvent.Loading -> {
            // Indicates some execution has been started internally (may display a loading screen)
            log("[LOADING]")
        }
        is CafUnifiedEvent.Loaded -> {
            // Indicates internal execution has been completed (may hide a loading screen)
            log("[LOADED]")
        }
        is CafUnifiedEvent.Success -> {
            // When the module is successfully completed, the callback receives the name of the module and the results
            event.response.forEach {
                log("[SUCCESS] moduleName: ${it.moduleName}")
                log("[SUCCESS] result: ${it.result}")
            }
        }
        is CafUnifiedEvent.Error -> {
            // Captures errors that occur during execution and allows fault handling logic to be implemented
            log("[ERROR] ${event.message}")
        }
        is CafUnifiedEvent.Cancelled -> {
            // Informs that the operation was canceled by the user or due to an execution failure
            log("[CANCELLED]")
        }
    }

Configured Flow Start

After building the sdkBuilder object with all configurations and the callback defined, the capture flow is started by calling the start() method. This method receives the context (application context is recommended) and initiates the sequential execution of the configured modules.

Code to start the flow:

sdkBuilder.start(this)

Process details

• Context: the parameter passed to start() must be a valid context (e.g., the current application instance), allowing the SDK to display the capture screens and manage UI transitions.

• Sequential Execution: the SDK starts the modules in the order defined in presentationOrder. Each module is executed sequentially and, upon completion, triggers the next, ensuring that the flow follows the established logic.

• Callback Integration: during execution, the SDK uses the unified callback to send the corresponding events (loading, loaded, success, etc.), allowing the application to react in real-time according to the flow state.

Complete a session

The completion or conclusion of a session in CafSDK occurs when all configured modules have been executed, or when an error/cancellation occurs in the flow.

Complete session definition

• Complete Execution: the session is considered complete when each module in the capture flow triggers a Success event, indicating that all operations were successfully performed.

• Flow Interruption: if an error occurs or if the user cancels the process at any point, the session is interrupted, and the Error or Cancelled event is triggered, allowing the application to take the necessary measures.

Completion events

• Success:

  • Returns results after all modules complete when waitForAllServices is enabled otherwise each module that ends successfully sends a CafUnifiedEvent.Success event, which includes:

    • moduleName: identifies the module that completed the operation (e.g., "documentDetector" or "faceLiveness").

    • result: a map (Map<String, Any>) containing the result data obtained by the module's execution. This data may include information relevant to the process, such as captured images or validation results.

• Error/Cancelled:

  • If the flow is interrupted due to a failure or cancellation:

    • Error: a CafUnifiedEvent.Error event is triggered with a descriptive message of the problem, allowing the implementation of recovery logic or user notifications.

    • Cancelled: if the process is canceled (e.g., by the user), the CafUnifiedEvent.Cancelled event is triggered, allowing resource cleanup or the display of informative messages.

These steps ensure that you have a complete and technical view of the CafSDK flow initialization and completion process, allowing for simplified integration and the implementation of appropriate strategies for handling each step of the capture flow.

These steps ensure that you have a complete and technical view of the CafSDK flow initialization and completion process, allowing for simplified integration and the implementation of appropriate strategies for handling each step of the capture flow.

---

Advanced flow customization

Learn how to customize and adjust the CafSDK capture flow to meet specific business and user experience requirements.

Execution order

• The order in which the modules will be executed is defined in the presentationOrder field of the CafSdkConfiguration object.

• This sequence is fundamental, as it directly impacts the flow logic. For example, if the process requires the document to be captured before facial verification, the order must reflect this priority.

Specific configuration

To customize the modules individually, use the setDocumentDetectorConfig and setFaceLivenessConfig methods. They allow you to adjust critical parameters, such as:

• Capture time: defines the timeout for the user to perform manual capture.

• Timeout: establishes the maximum waiting limit for a service response.

• Debug flags: enable or disable debug modes to facilitate problem identification during development.

• Layout and other parameters: allow configuring visual and operational elements specific to each module.

Visual customization

With the CafColorConfiguration object, it is possible to align the visual identity of the capture flow with your application's brand. This customization ensures that visual elements (buttons, backgrounds, and indicators) maintain consistency with the application's design.

Logging and monitoring

The unified callback implements different log levels (DEBUG, USAGE, INFO), which enables a detailed view of each step of the flow. These logs are essential for integrating with monitoring tools, adjusting performance, or identifying problems in real time.

Example of a implementation

    private fun startCaf() {
        val sdkConfiguration = CafSdkConfiguration(
            presentationOrder = listOf(CafModuleType.FACE_LIVENESS, CafModuleType.DOCUMENT_DETECTOR),
            colorConfig = CafColorConfiguration(primaryColor = "#0000FF", secondaryColor = "#00FF00"),
            waitForAllServices = true // Optional, default is true
        ).apply {
            setDocumentDetectorConfig(
                CafDocumentDetectorConfig(
                    flow = listOf(DocumentDetectorStep(Document.RG_FRONT), DocumentDetectorStep(Document.RG_BACK)),
                    useAdb = true,
                    useDebug = true,
                    useDeveloperMode = true,
                    manualCaptureEnabled = true,
                    manualCaptureTime = 45,
                    requestTimeout = 60,
                    showPopup = true
                )
            )
            setFaceLivenessConfig(
                CafFaceLivenessConfig(
                    loading = true,
                    debugModeEnabled = true
                )
            )
        }
        CafSdkProvider.Builder(
            mobileToken = MOBILE_TOKEN,
            personId = PERSON_ID,
            environment = CafEnvironment.PROD,
            configuration = sdkConfiguration,
            callback = ::callbackEvent
        )
            .build()
            .start(requireContext().applicationContext)
    }

    private fun callbackEvent(event: CafUnifiedEvent): Unit = when (event) {
        is CafUnifiedEvent.Log -> {
            // Informative logs, useful for debugging and monitoring
            log("[LOG] ${event.level}: ${event.message}")
        }

        is CafUnifiedEvent.Loading -> {
            // Indicates some execution has been started internally (may display a loading screen)
            log("[LOADING]")
        }

        is CafUnifiedEvent.Loaded -> {
            // Indicates internal execution has been completed (may hide a loading screen)
            log("[LOADED]")
        }

        is CafUnifiedEvent.Success -> {
            // When the module is successfully completed, the callback receives the name of the module and the results
            event.response.forEach {
                log("[SUCCESS] moduleName: ${it.moduleName}")
                log("[SUCCESS] result: ${it.result}")
            }
        }

        is CafUnifiedEvent.Error -> {
            // Captures errors that occur during execution and allows fault handling logic to be implemented
            log("[ERROR] ${event.message}")
        }

        is CafUnifiedEvent.Cancelled -> {
            // Informs that the operation was canceled by the user or due to an execution failure
            log("[CANCELLED]")
        }
    }

---

Face Liveness configuration

The integration of the Caf Face Liveness (FL) module is done through its configuration in the CafSdkConfiguration object. Once defined, the flow automatically executes the module in the corresponding position defined in the presentation order.

The Face Liveness configuration is done through the CafFaceLivenessConfig object, where the parameters that the SDK will use during its execution are informed. Check out the main configuration methods available:

Method	Type	Description
setLoading	Boolean	Enables or disables the loading screen. The default is: false.
setAuthBaseUrl	String	Define a URL do proxy Defines the reverse proxy URL for authentication. Must use the HTTPS protocol. Optional. Required only for reverse proxy.
setLivenessBaseUrl	String	Defines the reverse proxy URL for Face Liveness verification. Must use the WSS protocol. Optional. Required only for reverse proxy.
setCertificates	List	Defines the Base64 (SHA-256) encoded certificates for the reverse proxy. Optional. Required only for WSS via proxy.
setScreenCaptureEnabled	Boolean	Enables or disables screen capture. The default is: false.
setDebugModeEnabled	Boolean	Enables or disables log generation to assist with debugging during integration. The default isfalse.
setSdkType	CafFaceLivenessPlatform	Informs which platform is running the SDK. The default is CafFaceLivenessPlatform.NATIVE_ANDROID.

Example configuration for Face Liveness:

sdkConfiguration.setFaceLivenessConfig(
    CafFaceLivenessConfig(
        loading = true,
        authBaseUrl = "https://seu-auth-base-url.com",
        livenessBaseUrl = "wss://seu-liveness-base-url.com",
        certificates = listOf("certificado1", "certificado2"),
        screenCaptureEnabled = true,
        debugModeEnabled = true
    )
)

Results

After the successful execution, a CafUnifiedEvent.Success event is triggered, which contains:

• moduleName: the module identifier name (e.g., "faceLiveness").

• result: a map (Map<String, Any>) with the verification data.

Then, this data is processed by the unified callback, allowing the user interface to be updated or the flow to continue as needed.

---

Custom configurations - Face Liveness

Use custom configurations to direct requests through secure proxies and ensure that the correct protocols (WSS for Face Liveness and HTTPS for authentication) are used.

Reverse proxy configuration (optional)

This advanced configuration allows you to direct Face Liveness module connections through a reverse proxy, using the WSS (Web Socket Secure) protocol. Follow the steps to configure correctly:

• Proxy URL: define your proxy to communicate with the desired endpoint. For example, you can use: wss://us.rp.secure.iproov.me/ws or another compatible URL.

• Face Liveness URL Configuration: use the .setLivenessBaseUrl method to configure the Face Liveness URL. Remember that the protocol must be WSS.

• Certificate Definition: use the .setCertificates method to define the necessary certificates. These certificates must be the Base64 encoded SHA256 hashes of the proxy certificates.

Code example:

sdkConfiguration.setFaceLivenessConfig(
    CafFaceLivenessConfig(
        livenessBaseUrl = "wss://my.proxy.io/ws/",
        certificates = listOf(
            "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
            "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
            "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
        )
    )
)

Reverse Proxy for Authentication (optional)

For authentication communication, it is necessary to configure the reverse proxy with an HTTPS URL. This configuration directs authentication requests to the appropriate environment.

• Proxy URL: define your proxy to communicate. For example, you can use: https://api.public.caf.io/.

• Authentication URL Configuration: use the .setAuthBaseUrl method to specify the authentication URL, ensuring the HTTPS protocol is used.

Code example:

sdkConfiguration.setFaceLivenessConfig(
    CafFaceLivenessConfig(
        authBaseUrl = "https://my.proxy.io/v1/faces/"
    )
)

Note: in practice, both configurations (for authentication and Face Liveness) can be combined into a single instance ofCafFaceLivenessConfig.

Configuration Structures

When using the UI module (with the -ui suffix), you will be using Caf's proprietary screens, which have some customization possibilities. Check the details:

Caf Face Liveness Instructions Screen

This structure allows you to customize the Face Liveness instruction screen.

Property	Type	Description	Default value
image	String?	Image displayed in the screen header. The value can be a URL, the resource ID (in string format) or the resource name present in the drawable folder.	null
title	String?	Screen title (e.g., "Instructions to Scan Face").	null
description	String?	Brief descriptive text (e.g., "Follow the steps below").	null
steps	List<String>?	Ordered list of instructions (e.g., listOf ("Keep the phone steady"; "Good lighting")).	null
buttonText	String?	Text for the confirmation button (e.g., "Start scanning").	null

Caf Color Configuration

This structure allows you to customize the global colors of all interfaces. The colors follow the standard RGB or ARGB.

Property	Type	Description	Format
primaryColor	String	Main color for buttons and highlights.	Hex code (eg, #FF0000)
secondaryColor	String	Secondary color for complementary elements.	Hex code
backgroundColor	String	Screen background color.	Hex code
contentColor	String	Color used for texts and icons.	Hex code
mediumColor	String	Neutral color for elements like progress bars.	Hex code

Code examples

Check out the example on how to configure the Face Liveness module with instructions, reverse proxy (for authentication and verification), and interface customization.

val sdkConfiguration = CafSdkConfiguration(
      presentationOrder = listOf(...),
      colorConfig = CafColorConfiguration(
         primaryColor = "#FF0000",
         secondaryColor = "#00FF00",
         backgroundColor = "#FFFFFF",
         contentColor = "#000000",
         mediumColor = "#D1D1D1"
      )
)
sdkConfiguration.setFaceLivenessConfig(
   CafFaceLivenessConfig(
        loading = true,
        authBaseUrl = "https://my.proxy.io/v1/faces/",
        livenessBaseUrl = "wss://my.proxy.io/ws/",
        certificates = listOf(
            "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
            "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
            "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
        ),
        screenCaptureEnabled = true,
        debugModeEnabled = true
   )
)
sdkConfiguration.setCafFaceLivenessInstructionsScreen(
   CafFaceLivenessInstructionsScreen(
      image = R.drawable.scan_icon.toString()
      title = "Escaneie seu Rosto",
      description = "Siga os passos abaixo:",
      steps = listOf("Mantenha o telefone estável", "Garanta boa iluminação"),
      buttonText = "Iniciar Escaneamento",
   )
)

---

More information

Certificate requirements

• Certificates: they must be the Base64 encoded SHA-256 hashes of the SPKI (Subject Public Key Info) of the certificate.

Protocol application

• Face Liveness: The URL for Face Liveness must use the wss:// when using a reverse proxy.

• Authentication: The URL for authentication must use the https:// when using a reverse proxy.

---

Document Detector configuration

The Caf Document Detector (DD) module is configured similarly to Face Liveness, but with a focus on document capture and processing.

Configuration and execution

In CafSdkConfiguration, configure the specific Document Detector parameters, which determine the document capture behavior.

Main parameters:

• flow: a list of steps (DocumentDetectorStep) that defines which document and which angles or parts should be captured.

• useAdb, useDebug, and useDeveloperMode: flags that assist in development and execution in test environments.

• manualCaptureEnabled and manualCaptureTime: configure whether manual capture is allowed and what the timeout for the action is.

• requestTimeout: maximum time to wait for server responses or user actions.

• showPopup: determines whether a confirmation or instruction message will be presented to the user.

Configuration example for Document Detector:

sdkConfiguration.setDocumentDetectorConfig(
    CafDocumentDetectorConfig(
        flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
        useAdb = true,
        useDebug = true,
        useDeveloperMode = true,
        manualCaptureEnabled = true,
        manualCaptureTime = 45,
        requestTimeout = 60,
        showPopup = true
    )
)

Results

• Upon completing document capture and processing, the Document Detector module triggers a CafUnifiedEvent.Success event.

• This event includes the moduleName (e.g.,"documentDetector") and a result containing the captured data.

• The unified callback can then use this information to proceed to the next step or to store the results as needed.

---

Custom configurations - Document Detector

To configure the Caf Document Detector, use the CafDocumentDetectorConfig structure, which includes:

• Document capture flow steps.

• User interface (UI) layout customization.

• Feedback messages.

• Upload behavior.

• Proxy settings.

Core configuration

Properties of CafDocumentDetectorConfig.

Property	Type	Description
flow	List<DocumentDetectorStep>	Defines the document capture flow. See DocumentDetectorStep
layoutId	Int?	Custom layout ID.
uploadSettings	UploadSettings?	Settings for document upload. See UploadSettings
manualCaptureEnabled	Boolean?	Enables or disables manual capture.
manualCaptureTime	Int?	Timeout for manual capture (in seconds).
requestTimeout	Int?	Timeout for requests (in seconds).
showPopup	Boolean?	Enables or disables popups before capture.
proxySettings	ProxySettings?	Proxy settings. See ProxySettings
previewShow	Boolean?	Enables or disables the preview of the captured image.
previewTitle	String?	Sets the title displayed on the screen.
previewSubTitle	String?	Sets the subtitle displayed on the screen.
previewConfirmationLabel	String?	Sets the message displayed on the confirmation button.
previewRetryLabel	String?	Sets the message displayed on the button for a new capture.
messageSettings	MessageSettings?	Message settings displayed during capture. See MessageSettings
getUrlExpireTime	String?	Defines how long the image URL will remain active on the server until it expires. Accepts intervals such as 30m (minutes), 24h (hours), or 10d (days).
allowedPassportCountryList	List<CountryCodesList>?	List of allowed countries for passports. See CountryCodesList
useDebug	Boolean?	Allows the app to run in debug mode when true. Not recommended for production
useDeveloperMode	Boolean?	Enables developer mode when true. Not recommended for production
useAdb	Boolean?	Enables Android Debug Bridge (ADB) debugging mode when true. Not recommended for production

DocumentDetectorStep

To create a capture flow, you must create an array of DocumentDetectorStep, where each element represents a capture step. To build each DocumentDetectorStep object, you can use the following:

val detectorStep = DocumentDetectorStep(Document.RG_FRONT)

Property	Description
document: Document	Specifies the document to be captured in the step. Check the supported types below.
setStepLabel(stepLabel: Int)	Sets the text displayed at the bottom of the layout.
setIllustration(illustration: Int)	Sets the illustration displayed in the popup before capture.
showStepLabel(showStepLabel: Boolean)	Toggles the visibility of the text at the top of the layout.

Supported Documents

Name	Description
RG_FRONT	Front side of the RG document, where the photo is located.
RG_BACK	Back side of the RG document.
RG_FULL	Open RG document, displaying both the front and back sides together.
CNH_FRONT	Front side of the CNH document, where the photo is located.
CNH_BACK	Back side of the CNH document.
CNH_FULL	Open CNH document, displaying both the front and back sides together.
CRLV	CRLV document.
RNE_FRONT	Front side of the RNE or RNM document.
RNE_BACK	Back side of the RNE or RNM document.
PASSPORT	Passport document, displaying the photo and personal data.
CTPS_FRONT	Front side of the CTPS document, where the photo is located.
CTPS_BACK	Back side of the CTPS document.
ANY	Allows submission of any type of document, including all those listed above or any other unclassified document.

UploadSettings

Configures the settings related to document upload.

Property	Description
.setEnable(enable: Boolean)	Enables or disables this feature.
.setCompress(enable: Boolean)	Enables or disables file compression before upload.
.setFileFormats(fileFormats: Array<FileFormat>)	Specifies the accepted file formats for upload.
.setMaxFileSize(maxFileSize: Int)	Sets the maximum file size limit in KB.
.setActivityLayout(activityLayout: Int)	Defines the background layout for document upload.
.setPopUpLayout(popUpLayout: Int)	Defines the popup layout for the document upload request.

Currently, the supported file formats are:

Type	Value
PNG	image/png
JPG	image/jpg
JPEG	image/jpeg
PDF	application/pdf
HEIF	image/heif

ProxySettings

For the SDK to use a proxy when making requests, you must configure an instance of the ProxySettings class.

Constructor Method

Property	Type	Description
hostname	String	Sets the domain or IP address of the proxy service.
port	String	Sets the port to be used.

Optional Methods

setAuthentication(String user, String password)

Sets the authentication parameters for the proxy, if necessary.

Property	Description
user	Username to be used for authentication.
password	Password to be used for authentication.

setProxyCertificate(@RawRes Integer proxyCertificate)

If your proxy server uses a self-signed SSL certificate or one issued by a non-public Certification Authority (CA), add the CA certificate in PEM or DER format to the res/raw/ directory (e.g., res/raw/proxy_certificate) and pass the file identifier as an argument (e.g., R.raw.proxy_certificate).

Property	Description
proxyCertificate	ID of the proxy certificate file.

setMTLSConfig(@RawRes Integer clientCertificate, String password)

If your proxy server supports mTLS, save the client certificate in PKCS12 format (.p12) to the res/raw/ directory (e.g., res/raw/client_certificate) and pass the file identifier (e.g., R.raw.client_certificate) and the private key as arguments.

Property	Description
clientCertificate	ID of the client certificate file.
password	Private key to be used.

MessageSettings

To customize the messages displayed during capture, use the MessageSettings constructor by passing the corresponding values for each message. Below are the constructor parameters and their descriptions:

Property	Description
waitMessage	Message displayed when starting the camera.
fitTheDocumentMessage	Message prompting the user to fit the document within the frame.
holdItMessage	Message displayed during the capture process.
verifyingQualityMessage	Message displayed during the quality verification request.
lowQualityDocumentMessage	Message displayed when document capture fails due to low quality.
uploadingImageMessage	Message displayed when saving the captured image to the server.
openDocumentWrongMessage	Message displayed if an open document is detected.
unsupportedDocumentMessage	Message for unsupported documents.
documentNotFoundMessage	Message displayed when no document is detected.
sensorLuminosityMessage	Message displayed when the brightness level is too low.
sensorOrientationMessage	Message displayed when the orientation threshold is not met.
sensorStabilityMessage	Message displayed when the device is not stable enough.
popupDocumentSubtitleMessage	Subtitle message displayed in the popup presenting the document illustration.
positiveButtonMessage	Message displayed on the confirmation button.
aiScanDocumentMessage	Message prompting the user to scan a document.
aiGetCloserMessage	Message prompting the user to get closer to the document.
aiCentralizeMessage	Message prompting the user to center the document on the screen.
aiMoveAwayMessage	Message prompting the user to move away from the document.
aiAlignMessage	Message prompting the user to align the document.
aiTurnDocumentMessage	Message prompting the user to rotate the document 90 degrees.
aiCapturedMessage	Message confirming that the document has been captured.
wrongDocumentMessage	Message displayed when the document type is incorrect.

CountryCodesList

Complete list of the official codes currently assigned according to ISO 3166-1 alpha-3.

Customizing Screens

When using the UI module (with the -ui suffix), you will be using CAF's proprietary screens. These screens offer customization options as described below.

CafDocumentDetectorInstructionsScreen

This structure allows you to customize the instructions screen.

Property	Type	Description
image	String?	Image displayed in the header of the screen. The value can be a URL, a resource ID (as a string), or the name of the resource in the drawable folder.
title	String?	Screen title (e.g., "Instructions for Scanning the Face").
description	String?	Brief descriptive text (e.g., "Follow the steps below").
steps	List<String>?	Ordered list of instructions (e.g., listOf("Keep the phone steady", "Ensure good lighting")).
buttonText	String?	Text for the confirmation button (e.g., "Start Scanning").

CafDocumentDetectorDocumentSelectionScreen

This structure allows you to customize the document selection screen.

Property	Type	Description
documents	List<CafDocument>	List of documents to be displayed. The value can be a URL, a resource ID (as a string), or the name of the resource in the drawable folder.
title	String?	Screen title (e.g., "Select the Document").
description	String?	Brief descriptive text (e.g., "Choose the document you want to submit").

CafDocument

Name	Description
RGFront	Front side of the RG document, where the photo is located.
RGBack	Back side of the RG document.
RGFull	Open RG document, displaying both the front and back sides together.
CnhFront	Front side of the CNH document, where the photo is located.
CnhBack	Back side of the CNH document.
CnhFull	Open CNH document, displaying both the front and back sides together.
Crlv	CRLV document.
RneFront	Front side of the RNE or RNM document.
RneBack	Back side of the RNE or RNM document.
Passport	Passport document, displaying the photo and personal data.
CtpsFront	Front side of the CTPS document, where the photo is located.
CtpsBack	Back side of the CTPS document.
Other	Allows submission of any other type of document that is not classified.

CafColorConfiguration

This structure allows you to customize the global colors of all interfaces. The colors follow the RGB or ARGB standard.

Property	Type	Description	Format
primaryColor	String	Primary color for buttons and highlights.	Hex Code (e.g., #FF0000)
secondaryColor	String	Secondary color for complementary elements.	Hex Code
backgroundColor	String	Background color of the screen.	Hex Code
contentColor	String	Color used for text and icons.	Hex Code
mediumColor	String	Neutral color for elements like progress bars.	Hex Code

Code Examples

The following example demonstrates how to configure the DocumentDetector module with instructions and interface customization:

private fun isDarkMode() = 
    (resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) == Configuration.UI_MODE_NIGHT_YES

val colorConfigConfiguration = if (isDarkMode()) {
    CafColorConfiguration(
        primaryColor = "#00FF00",
        secondaryColor = "#FF0000",
        backgroundColor = "#000000",
        contentColor = "#FFFFFF",
        mediumColor = "#D1D1D1"
    )
} else {
    CafColorConfiguration(
        primaryColor = "#FF0000",
        secondaryColor = "#00FF00",
        backgroundColor = "#FFFFFF",
        contentColor = "#000000",
        mediumColor = "#D1D1D1"
    )
}

val sdkConfiguration = CafSdkConfiguration(
    presentationOrder = listOf(...),
    colorConfig = colorConfigConfiguration
)

sdkConfiguration.setDocumentDetectorConfig(
    CafDocumentDetectorConfig(
        flow = listOf(), // When using UI, this can be empty because the list will be defined in CafDocumentDetectorDocumentSelectionScreen
        uploadSettings = false, // When using UI, this will be ignored as the user can select on the screen
        useDebug = true,
        useDeveloperMode = true,
        useAdb = true
    )
)

sdkConfiguration.setCafDocumentDetectorDocumentSelectionScreen(
    CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront, CafDocument.RGBack, CafDocument.CnhFront, CafDocument.CnhBack),
        title = "Custom title",
        description = "custom description"
    )
)

sdkConfiguration.setCafDocumentDetectorInstructionsScreen(
    CafDocumentDetectorInstructionsScreen(
        title = "Custom title",
        steps = listOf("Keep the phone steady", "Ensure good lighting"),
        buttonText = "Start"
    )
)

CafUnifiedResponse

public class CafUnifiedResponse(
    public val moduleName: String,
    public val result: Map<String, Any>,
)

Property	Type	Description
moduleName	String	Name of the module issuing its result in the success event.
result	Map<String, Any>	Map containing the data obtained by the module's execution.

---

Additional resources

ProGuard/R8 Rules

Check out the code block with the ProGuard/R8 rules necessary for CafSDK and its dependencies to function correctly even after code obfuscation and optimization. These rules preserve essential information (such as signatures, annotations, and internal classes) and prevent critical classes from being removed or altered.

# The Android pre-handler for exceptions is loaded reflectively (via ServiceLoader).
-keep class kotlinx.coroutines.experimental.android.AndroidExceptionPreHandler { *; }

### GSON ##################################################################
# Gson uses generic type information stored in a class file when working with fields.
# ProGuard removes such information by default, so configure it to keep all of it.
-keepattributes Signature
# For using GSON @Expose annotation
-keepattributes *Annotation*
### END GSON ##################################################################

### Retrofit ##################################################################
# Preserve generic signatures, inner classes, and enclosing methods for Retrofit reflection.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Retain runtime-visible annotations on methods and parameters.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Keep annotation default values.
-keepattributes AnnotationDefault
# Retain service method parameters for interfaces with Retrofit annotations.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suppress warnings for build tooling and certain JSR 305 annotations.
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
# Explicitly keep Retrofit interfaces to prevent nullification by R8.
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
# Preserve continuations used by Kotlin suspend functions.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# For R8 full mode: keep generic return types for Retrofit methods.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preserve Retrofit Response class.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### END Retrofit ##############################################################

### OkHttp ####################################################################
# Suppress warnings for JSR 305 annotations.
-dontwarn javax.annotation.**
# Adapt resource filenames for internal public suffix database.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suppress warnings for Animal Sniffer and platform-specific classes.
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
# Keep all OkHttp and Okio classes.
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### END OkHttp ################################################################

### Kotlin Serialization ######################################################
# Keep Companion objects for serializable classes.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Keep serializer functions on companion objects.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Retain INSTANCE and serializer for serializable objects.
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve Companion objects in kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve serializer lookup for serializable classes (adjust package name as needed).
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### END Kotlin Serialization #################################################

### AutoValue ################################################################
-dontwarn com.google.auto.**
-dontwarn autovalue.shaded.com.**
-dontwarn sun.misc.Unsafe
-dontwarn javax.lang.model.element.Modifier
### END AutoValue ############################################################

### CAF - Combate a Fraude ######################################################
# Keep exceptions attributes.
-keepattributes Exceptions
# Preserve all classes, interfaces, and class members for CAF modules.
-keep class com.caf.facelivenessiproov.** { *; }
-keep class com.combateafraude.documentdetector.** { *; }
-keep class com.combateafraude.** { *; }
-keep interface com.combateafraude.** { *; }
-keep class io.caf.** { *; }
-keep interface io.caf.** { *; }
-keepclassmembers class com.combateafraude.** { *; }
# Suppress warnings for java.nio.file and certain OkHttp internal classes.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Keep fields in classes extending GeneratedMessageLite (for Tink usage).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preserve TensorFlow classes.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preserve IProov classes and Protobuf classes.
-keep public class com.iproov.sdk.IProov { public *; }
-keep class com.iproov.** { *; }
-keep class com.iproov.**$* { *; }
-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }
-dontwarn com.google.protobuf.**
# Suppress warnings for concurrent Flow classes.
-dontwarn java.util.concurrent.Flow*
# Preserve Kotlin and kotlinx classes.
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
### END CAF - Combate a Fraude ##################################################

---

Technical Support and Usage Tips

Technical Support If you have any questions or difficulties with the integration, contact Caf's technical support.

Usage tips

• Run tests: perform tests on real devices to validate requirements and flow performance.

• Explore customizations: use advanced customization options to tailor the flow to your project's needs.

• Moniitor performance: integrate monitoring tools to track logs and the flow's performance in production.

---

Release notes

CafSDK v2.0.0

New Features

• Batch Results Flag: CafSDKConfiguration(waitForAllServices = true) now aggregates all module responses into a single Success(response: List<CafUnifiedResponse>).

• Unified CafUnifiedEvent.Success Update: CafUnifiedEvent.Success now always carries an array of responses.

• Improviments into UI screens.

• Added support for uploading documents with the DocumentDetector UI module.

Breaking Changes

• Signature of CafUnifiedEvent.Success changed to Success(response: List<CafUnifiedResponse>).

Migration Guide

1. Update to v2.0.0+.

2. Change handler to expect an array:

   is CafUnifiedEvent.Success -> {
        event.response.forEach {
            log("[SUCCESS] moduleName: ${it.moduleName}")
            log("[SUCCESS] result: ${it.result}")
        }
    }

CafSDK v1.4.0

New Features

• Introducing CafSDKProvider: A unified entry point for integrating Face Liveness and Document Detector modules with a single configuration.

• Builder Pattern: Simplified initialization using CafSDKProvider.Builder for modular, type-safe setup.

• Unified Configuration: Configure both modules using CafSDKConfiguration, including execution order (presentationOrder) and UI theming (CafColorConfiguration).

• Cross-Module Consistency: Shared authentication, environment, and logging across modules.

Documentation Updates

• Revised guides for integration.

• Added detailed examples for CafFaceLivenessConfig and CafDocumentDetectorConfig.

Configuration Enhancements

Face Liveness

• Customize instructions (CafInstructionsConfiguration).

• Configure reverse proxy endpoints (authBaseUrl, livenessBaseUrl).

Document Detector

• Define multi-step capture flows (CafDocumentDetectorStep).

• UI customization (CafDocumentDetectorLayout, CafMessageSettings).

• Proxy support (CafProxySettings).

Breaking Changes

• New integration Module: CafSDK

Migration Guide

1. Replace standalone module initializers with CafSDKProvider

2. Use CafDocumentDetectorStep(stepType:) instead of legacy constructors.