Captura de documentos

Descripción General​

El objetivo de este documento es proporcionar una guía detallada para desarrolladores sobre cómo integrar e implementar el SDK DocumentCaptureUI en tus aplicaciones iOS escritas en SwiftUI. Este SDK permite la captura de un comprobante de domicilio de manera eficiente, mostrando la cámara con una guía y devolviendo la ruta de la imagen capturada a la aplicación host.

Funcionalidad de la librería​

Al invocar el módulo de captura de documento, la librería nos llevará a la apertura de la cámara para el proceso de la captura del documento. Se nos presentará una pantalla con la cámara abierta y las instrucciones y recomendaciones para optimizar la toma de la fotografía. Una vez que se terminó el proceso de la captura de la fotografía la librería devolverá el control a la aplicación con los resultados del proceso

Al invocar el módulo de captura, el SDK abrirá la cámara y mostrará una pantalla con instrucciones para orientar al usuario en la toma de la fotografía. Tras capturar el documento, el SDK regresará el control a la aplicación host junto con la ruta de la imagen guardada en el dispositivo.

Compatibilidad

Lenguaje	Versión iOS
SwiftUI	iOS 13+

Incrustar y Firmar el Framework​

En Xcode iremos a la pestaña “General” en el target de la aplicación nos ubicamos en la sección “Frameworks, Libraries and Embedded Content” y en el nombre del framework DocumentCaptureUI.xcframework seleccionamos la opción “Embed & Sign” de la columna “Embed”.

1. En Xcode, ve a la pestaña “General” del target de tu aplicación.
2. En “Frameworks, Libraries and Embedded Content”, agrega DocumentCaptureUI.xcframework y selecciona la opción “Embed & Sign” en la columna “Embed”.

Requisitos Previos​

1. Permisos de Cámara: Agregar la clave de uso de cámara al archivo Info.plist:

Info.plist

<!-- Info.plist -->
<key>NSCameraUsageDescription</key>
<string>Por favor, concede permiso para usar la cámara.</string>

Ajusta el texto a tu mensaje deseado.

2. Agregar el Framework al Proyecto: En la vista (o estructura SwiftUI) donde vas a lanzar la captura, importa el módulo:

   • Arrastra DocumentCaptureUI.xcframework al proyecto.

   • Asegúrate de marcar la casilla “Copy items if needed”.

   • Selecciona el target o targets donde requieras usarlo.

3. Importar el SDK: En la vista (o estructura SwiftUI) donde vas a lanzar la captura, importa el módulo:

import DocumentCaptureUI

Iniciar el Proceso de Captura del Documento​

1. Declarar la Vista que Invoca el SDK: En la aplicación host, crea o modifica la vista SwiftUI desde la cual iniciarás la captura. Puedes usar un botón que presente la vista del SDK usando un fullScreenCover o un sheet. Por ejemplo:

import SwiftUI
import DocumentCaptureUI

struct DocumentCapture: View, CaptureDocumentVCDelegate {
    // Controla la presentación de la cámara
    @State private var showDocumentCapture = false
    
    var body: some View {
        VStack {
            Button("Iniciar captura") {
                showDocumentCapture = true
            }
        }
        .fullScreenCover(isPresented: $showDocumentCapture) {
            // Se inicializa la vista del framework
            CaptureUI(
                token: "TOKEN_PROPORCIONADO_POR_DICIO",
                urlVerify: "https://api.devdicio.net:8444/v1/sec_dev_pagos_middleware",
                delegate: self
            )
        }
    }
    
    // MARK: - CaptureDocumentVCDelegate
    
    /// Método del protocolo que recibe si la captura fue exitosa y la ruta de la imagen
    func pictureFinished(isSuccessfull: Bool, route: String) {
        print("Foto exitosa? \(isSuccessfull) ruta: \(route)")
        // Cierra el fullScreenCover
        showDocumentCapture = false
        
        // Aquí puedes procesar la imagen según tu lógica de negocio
    }
}

Nota: Si tu token y URL provienen de otras fuentes, sustitúyelos donde corresponda.

2. Implementar el Protocolo La vista que lanza el SDK debe adoptar el protocolo CaptureDocumentVCDelegate. Esto te obliga a implementar el método: • pictureFinished(isSuccessfull: Bool, route: String)

Dicho método te notifica el resultado de la captura: • isSuccessfull: true si la foto se guardó correctamente; false en caso contrario. • route: Ruta en el sistema de archivos de tu aplicación donde se guardó la foto. Si ocurre un error o se cancela la captura, la ruta podría ser una cadena vacía o un valor simbólico.

3. Ejemplo de Uso Completo

struct DocumentCapture: View, CaptureDocumentVCDelegate {
    @State private var showDocumentCapture = false
    
    var body: some View {
        VStack {
            Button("Iniciar captura") {
                showDocumentCapture = true
            }
        }
        .fullScreenCover(isPresented: $showDocumentCapture) {
            CaptureUI(
                token: "TOKEN_PROPORCIONADO_POR_DICIO",
                urlVerify: "https://api.devdicio.net:8444/v1/sec_dev_pagos_middleware",
                delegate: self
            )
        }
    }
    
    // MARK: - CaptureDocumentVCDelegate
    func pictureFinished(isSuccessfull: Bool, route: String) {
        print("Foto exitosa? \(isSuccessfull) ruta: \(route)")
        // Cierra la pantalla
        showDocumentCapture = false
        
        // Aquí puedes manejar la ruta o mostrar un mensaje al usuario.
    }
}

Referencia de la Vista Principal del Framework

Dentro del framework, la vista principal es CaptureUI. Recibe:

•   token: String con el token proporcionado.

•   urlVerify: String con la URL base que se usará para verificar el token.

•   delegate: CaptureDocumentVCDelegate, donde se notifican los resultados.

Consideraciones Adicionales

• Manejo de Errores: El SDK internamente maneja casos de permisos denegados o token no autorizado. En caso de que el usuario deniegue la cámara o micrófono, se le mostrará una alerta indicándole que debe conceder permisos.

• Estilos y UI: Puedes personalizar la presentación (por ejemplo, usar .sheet en lugar de .fullScreenCover), siempre que el contenedor sea una vista SwiftUI.

• Integración en Proyectos Existentes: Asegúrate de que tu proyecto cumpla con iOS 13+ (o la versión que hayas definido). Para versiones anteriores, este SDK no es compatible.

• Versionado: Verifica la versión específica de VideoRecorderUI.xcframework que recibas, en caso de que existan actualizaciones o cambios en la API.