> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/ios/comecando-com-o-sdk.md).

# Começando com o SDK

## Conheça o CafSDK

Essa documentação técnica aborda a **implementação do CafSDK para iOS**, com detalhes sobre a configuração, inicialização, execução dos fluxos de captura e personalizações avançadas.

Atualmente, o CafSDK integra 2 módulos principais: **Face Liveness (FL)** e **Document Detector (DD)**, executados de forma sequencial com uma interface de configuração unificada.

## O que é Face Liveness

É o módulo que valida a autenticidade de um rosto capturado por aplicativo de foto, garantindo que a imagem corresponda à uma pessoa real.

### Características técnicas:

* Configuração de URLs para autenticação (`authBaseUrl`) e verificação de prova de vida (liveness) (`livenessBaseUrl`).
* Flags para habilitar captura de tela (screen capture) e modo de depuração (debug mode).
* Suporte à múltiplos provedores de autenticação.

## O que é Document Detector

É o módulo que permite a captura e o processamento de documentos (Ex.: RG, CPF, Passaporte, etc.).

### Características técnicas:

* Configuração de um fluxo de etapas (flow) definidas por `DocumentDetectorStep` para a captura do documento.
* Parâmetros operacionais, como timeout, flags de captura manual, entre outras configurações.
* Possibilidade de uso da câmera para validações de enquadramento, ou upload de arquivo do documento.

***

## Comece a usar o SDK

### Adicione a dependência

O CafSDK oferece suporte à integração tanto **pelo Swift Package Manager (SPM) quanto pelo CocoaPods**, proporcionando flexibilidade para escolher o gerenciador de dependências que melhor se adapta ao seu projeto. Este guia explica as etapas necessárias para adicionar o CafSDK ao seu projeto iOS e fornece detalhes sobre os módulos disponíveis.

### Requisitos para adicionar

Para usar os módulos do CafSDK no iOS, certifique-se de que seu projeto aos requisitos mínimos:

| Requisito                 | Versão |
| ------------------------- | ------ |
| **iOS Deployment Target** | 13.0+  |
| **Xcode**                 | 15.4+  |
| **Swift**                 | 5.10+  |

> **Importante**: configure o Info.plist do seu projeto com as permissões necessárias para acesso à câmera e à rede.

* **CAF Mobile Token**: valid [CAF mobileToken](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md)

### Etapas para adicionar

#### Pelo Swift Package Manager (SPM)

#### Etapa 1 - Adicionar a dependência

Abra o arquivo `Package.swift` do seu projeto e adicione a seguinte dependência. Isso informa ao Swift Package Manager onde localizar o repositório do CafSDK:

```swift
dependencies: [
    .package(url: "https://github.com/combateafraude/caf-ios-sdk.git", from: "0.1.1")
]
```

#### Etapa 2 - Inclua os produtos desejados

Após adicionar a dependência, inclua os produtos necessários no destino do seu aplicativo. Isso permite que você integre o SDK completo ou selecione apenas módulos específicos, conforme suas necessidades:

```swift
.target(
    name: "YourApp",
    dependencies: [
        .product(name: "CafSDK", package: "CafSDK"),            // Full SDK
        .product(name: "DocumentDetector", package: "CafSDK"),    // Only DocumentDetector
        .product(name: "CafFaceLiveness", package: "CafSDK"),       // Only CafFaceLiveness
        .product(name: "IproovProvider", package: "CafSDK"),        // Optional iProov provider
        .product(name: "FaceTec2DProvider", package: "CafSDK")      // Optional FaceTec 2D provider
    ]
)
```

#### Informações adicionais

* **Modularidade:** integre apenas os módulos necessários para manter seu projeto leve.
* **Compatibilidade:** o SDK é compatível com iOS 13.0+ e foi desenvolvido com Swift 5.10+.
* **Gerenciamento de versão:** a declaração de dependência de: "0.1.1" garante o uso de uma versão compatível. Sempre verifique o repositório oficial para obter a versão mais recente.

#### Pelo CocoaPods

#### Etapa 1 - Atualize seu Podfile

Para integrar o CafSDK usando CocoaPods, abra o Podfile do seu projeto e adicione as seguintes linhas. Isso instruirá o CocoaPods a baixar os artefatos necessários do repositório oficial:

```bash
# Full SDK
pod 'CafSDK'

# Only DocumentDetector
pod 'CafSDK/DocumentDetector'

# Only CafFaceLiveness
pod 'CafSDK/CafFaceLiveness'

# Optional iProov provider
pod 'CafSDK/IproovProvider'

# Optional FaceTec 2D provider
pod 'CafSDK/FaceTec2DProvider'
```

#### Etapa 2 - Instale as dependências

Após atualizar o seu Podfile, abra um terminal no diretório raiz do seu projeto e execute:

```bash
pod install
```

Esse comando baixa e integra todos os módulos específicos no seu projeto.

#### Informações adicionais

* **Integração seletiva:** escolha apenas os módulos necessários para o seu projeto, otimizando o desempenho.
* **Gerenciamento automático de dependências:** o CocoaPods gerencia automaticamente a resolução de versões e conflitos de dependências.
* **Documentação e suporte:** para instruções mais detalhadas ou solução de problemas, consulte a documentação do CafSDK.

***

## Como inicializar o SDK

Este guia explica como inicializar o CafSDK no iOS. Ele abrange os requisitos, permissões, configuração global, configuração específica de módulos e a inicialização do builder.

### Permissões

Para que os módulos do SDK funcionem corretamente, você deve declarar as seguintes permissões no seu **Info.plist**:

#### Para Face Liveness:

* **Camera Usage Description** (`NSCameraUsageDescription`): explica por que o aplicativo precisa de acesso à câmera para detecção de rostos.
* **Network access:** nenhuma permissão explícita é necessária, mas certifique-se de que seu aplicativo suporte conexões seguras (HTTPS/WSS).

#### Para Document Detector:

* **Camera Usage Description** (`NSCameraUsageDescription`): necessário para capturar imagens de documentos.
* **Photo Library Usage Description** (`NSPhotoLibraryUsageDescription`):\
  necessário se o seu aplicativo suportar o envio de imagens da biblioteca (opcional).

***

### Configurações

O processo de inicialização é dividido em 2 partes: configuração global e configuração específica dos módulos.

#### Configuração global

Crie um objeto `CafSDKConfiguration`, que serve como o contêiner central para todas as configurações. Essa configuração define a ordem de execução dos módulos e a identidade visual (por meio de uma configuração de cores).

**Exemplo de código:**

```swift
let sdkConfig = CafSDKConfiguration(
    presentationOrder: [.faceLiveness, .documentDetector] //Required
)
```

#### Configuração específica de módulos

Após as configurações globais, configure cada módulo individualmente para ajustar os parâmetros operacionais, de segurança e visuais.

#### Configuração do Document Detector

Configure o módulo Document Detector especificando o fluxo de captura e opções como captura manual e confirmações em pop-up.

**Exemplo de código:**

```swift
sdkConfig.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .CNH_FULL)]
))
```

Consulte: [DocumentDetector](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md)\\

**Configuração do** **Face Liveness**

Configure o módulo Face Liveness para validar que o rosto capturado pertence a uma pessoa viva. Defina opções para indicadores de carregamento, endpoints e certificados de segurança.

**Exemplo de código:**

```swift
sdkConfig.setFaceLivenessConfig(CafFaceLivenessConfig())
```

Consulte: [FaceLiveness](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md)

***

## Inicialização do Builder

A inicialização do Builder é a etapa onde o fluxo de captura do CafSDK é configurado para a execução. Use o `CafSdkProvider.Builder` para fornecer os parâmetros necessários, incluindo um mobile token, person ID, ambiente e o callback unificado para tratar os eventos.

#### Exemplo de código:

```swift
// Create the SDK configuration with the desired modules and custom settings
var sdkConfig = CafSDKConfiguration(
        presentationOrder: viewModel.presentationOrder
    ).setDocumentDetectorConfig(CafDocumentDetectorConfig(flow: [DocumentDetectorStep(document: .CNH_FRONT)])) // Example required document
        .setFaceLivenessConfig(CafFaceLivenessConfig())

// Build the SDK with required parameters and a callback for events
let builder = CafSDKProvider.Builder(
    self,
    mobileToken: "your mobile token",
    personId: "person id",
    environment: .prod,
    configuration: sdkConfig,
    callback: { [weak self] event in
        self?.handleUnifiedEvent(event)
    }
)
let sdk = builder.build()

// Start the SDK session
sdk.start()

// Example unified event handler
private func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }
        switch event {
        case .loading:
            print("🔄 Loading...")
        case .loaded:
            print("🔄 Loaded")
        case .success(let response):
            print("✅ Success from \(response.moduleName):\n\(response.result)")
        case .error(let message):
            print("❌ Error:\n\(message)")
        case .cancelled:
            print("⚠️ Cancelled")
        case .log(let level, let message):
            print("[\(level)] \(message)")
        }
    }
}
```

#### Detalhes do processo

* **Configuração global:** define o fluxo geral e a aparência usando `presentationOrder` e `CafColorConfiguration`.
* **Configuração específica de módulo:** personaliza os módulos Document Detector e Face Liveness com configurações individuais (Ex.: fluxo de captura, indicador de carregamento, endpoints da API).
* **Inicialização com o Builder:** o padrão builder reúne todos os parâmetros necessários (mobile token, person ID, ambiente, configuração e callback) para criar e iniciar o SDK.

Seguindo essas etapas, seu projeto iOS será configurado corretamente para usar o CafSDK, garantindo uma integração robusta e eficiente dos módulos de detecção de documentos e verificação de rosto.

***

## Concluir uma sessão

Uma sessão completa no CafSDK abrange todo o fluxo, desde a inicialização até a finalização - seja essa finalização uma validação bem-sucedida, um erro ou um cancelamento pelo usuário.

#### Tratamento de Eventos da Sessão

O callback do builder retorna um conjunto de eventos definidos pela enumeração `CafUnifiedEvent`. Esses eventos, incluem:

* **Loading:** indica que o SDK está em processamento.
* **Loaded:** notifica que todos os módulos estão prontos.
* **Success (response: CafUnifiedResponse):** retorna o resultado após uma sessão bem-sucedida.
* **Error (message: String):** fornece uma mensagem de erro caso algo dê errado.
* **Cancelled:** indica que a sessão foi cancelada pelo usuário.
* **Log (level: CafLogLevel, message: String):** oferece informações detalhadas de log.

#### Importante

Uma sessão é considerada concluída quando todos os módulos do fluxo de captura tiverem terminado a sua operação com êxito ou quando o processo for interrompido por um erro ou um cancelamento. Em uma sessão completa:

**Execução completa:**\
Cada módulo que termina com sucesso, envia um `Success` event, incluindo:

* `moduleName:` identifica o módulo (Ex.: `"documentDetector"` or `"faceLiveness"`) que concluiu a operação.
* `result:` Um mapa (`[String: Any]`) que contém os dados da execução do módulo (tais como imagens captadas ou resultados de validação).

**Fluxo interrompido:**\
If an error occurs or the user cancels the process:

* **Error:** Um `CafUnifiedEvent.Error` evento é disparado com uma mensagem de erro descritiva, permitindo que você faça a recuperação ou notifique a pessoa usuária.
* **Cancelled:** Um `CafUnifiedEvent.Cancelled` evento é ativado, o que permite a você limpar recursos ou apresentar uma mensagem de cancelamento.

#### Exemplo de tratamento de eventos

Confira um exemplo de como tratar estes eventos em unified callback para iOS:

```swift
func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    switch event {
    case .loading:
        // Show a loading indicator
        break
    case .loaded:
        // Update UI to show that modules are ready
        break
    case .success(let response):
        // Process the successful response from the completed module
        print("Module: \(response.moduleName) Result: \(response.result)")
    case .error(let message):
        // Handle error state (display an alert, retry, etc.)
        print("Error: \(message)")
    case .cancelled:
        // Handle cancellation gracefully
        break
    case .log(let level, let message):
        // Log internal messages for debugging purposes
        print("[\(level)] \(message)")
    }
}
```

### Resumo

* **Sessão completa**: uma sessão é considerada completa quando todos os módulos configurados concluem suas tarefas com sucesso, ou quando ocorre um erro/cancelamento.
* **Gerenciamento centralizado**: O callback unificado garante que, independentemente do resultado, seu aplicativo será notificado e poderá tomar a ação apropriada.

Essa abordagem garante uma integração robusta com o CafSDK, lidando de forma eficiente com cada estado do fluxo de captura, do início ao fim.

***

## Fluxo avançado

Esta seção explica como personalizar e ajustar o fluxo de captura do CafSDK para atender a requisitos específicos de negócios e aprimorar a experiência de usuários no iOS.

#### Ordem de execução dos módulos

A ordem em qual os módulos são executados, é definida pelo campo `presentationOrder` do objeto `CafSDKConfiguration`.

Essa sequência é crucial, pois impacta diretamente a lógica do fluxo. Por exemplo, se o processo exigir que o documento seja capturado antes da validação facial, a ordem deve refletir essa prioridade.

#### Exemplo de código:

```swift
let sdkConfig = CafSDKConfiguration(
    presentationOrder: [.documentDetector, .faceLiveness],
    colorConfig: CafColorConfiguration(
        primaryColor: "#FF0000",
        secondaryColor: "#FFFFFF",
        contentColor: "#FF0000",
        backgroundColor: "FFFFFFF",
        mediumColor: "00FF00"
    )
)
```

### Configuração específica de módulos

Personalize módulos individuais usando os métodos `setDocumentDetectorConfig` e `setFaceLivenessConfig`. Esses métodos permitem ajustar parâmetros essenciais, como:

* **Tempo limite de captura**: define o tempo máximo para a captura manual.
* **Tempo limite de requisição**: estabelece o tempo máximo de espera por uma resposta do serviço.
* **Flags de depuração**: ativam ou desativam modos de depuração para identificar problemas durante o desenvolvimento.
* **Layout e outras configurações**: ajustam parâmetros visuais e operacionais específicos de cada módulo.

#### Personalização visual

Com o objeto `CafColorConfiguration`, é possível alinhar a identidade visual do fluxo de captura com o design do seu aplicativo. Isso garante que elementos visuais (botões, fundos e indicadores) sejam consistentes com a identidade da sua marca.

#### Registro de logs e monitoramento

O callback unificado implementa diferentes níveis de log (**DEBUG, USAGE, INFO**), permitindo o monitoramento detalhado de cada etapa do fluxo. Esses logs são essenciais para integração com ferramentas de monitoramento, ajustes de desempenho e identificação de problemas em tempo real.

#### Exemplo no callback:

```swift
callback = { event in
    switch event {
    case .log(let level, let message):
        // Log messages for detailed monitoring of the flow
        print("[LOG] \(level): \(message)")
    default:
        break
    }
}
```

#### Exemplo de encadeamento de configurações:

```swift
var sdkConfig = CafSDKConfiguration(
    presentationOrder: [.faceLiveness, .documentDetector],
    colorConfig: CafColorConfiguration(
        primaryColor: "#FF0000",
        secondaryColor: "#FFFFFF",
        contentColor: "#FF0000",
        backgroundColor: "FFFFFFF",
        mediumColor: "00FF00"
    )
)
.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .CNH_FULL)]
))
.setFaceLivenessConfig(CafFaceLivenessConfig())
```

Consulte: [DocumentDetector](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md) and [FaceLiveness](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md)

\*Ao encadear essas chamadas de configuração, você pode controlar com precisão o comportamento e a aparência de cada módulo no fluxo unificado.

***

## Configurações personalizadas - Face Liveness

O módulo Face Liveness no CafSDK oferece medidas robustas para garantir que o rosto da pessoa usuária seja real e de uma pessoa viva. Ele suporta vários provedores, como iProov e FaceTec2D, permitindo que você escolha ou combine soluções com base em seus requisitos.

Para opções de personalização detalhadas, consulte: [FaceLiveness Configurations](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md).

## Para configurar o Face Liveness

O objeto de configuração principal é o `CafFaceLivenessConfig`, que inclui:

* **Configuração de instruções**: instruções e etapas personalizáveis (via `CafInstructionsConfiguration`) que orientam a pessoa usuária.
* **Indicador de carregamento**: uma flag (`loadingEnabled`) para exibir um indicador de carregamento durante o processamento.
* **URLs de Endpoint**: especificação do `authBaseUrl` (HTTPS) e `livenessBaseUrl` (WSS) para comunicação com a API.
* **Certificados**: uma lista de certificados para comunicação segura (hashes base64 codificados em SHA-256 SPKI).

#### Exemplo de configuração:

```swift
    sdkConfig.setFaceLivenessConfig(CafFaceLivenessConfig(
    instructionsConfig: CafInstructionsConfiguration(
        enabled: true,
        title: "Scan Your Face",
        descriptionText: "Follow these steps:",
        steps: ["Hold the phone steady", "Ensure good lighting"],
        buttonTitle: "Start Scan",
        headerImage: UIImage(named: "scan_icon")
    ),
    loadingEnabled: true,
    authBaseUrl: "https://my.proxy.io/v1/faces/",
    livenessBaseUrl: "wss://my.proxy.io/ws/",
    certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]
))
```

### Como funciona

Quando o `faceLivenessConfig` é definido na sua `CafSDKConfiguration`, o módulo Face Liveness será executado automaticamente quando a sua posição na ordem de apresentação for atingida.

Após a execução bem-sucedida, um evento `CafUnifiedEvent.Success` é acionado, contendo:

* **moduleName:** o identificador do módulo (Ex.: `"faceLiveness"`).
* **result:** um dicionário (`[String: Any]`) contendo os dados resultantes da verificação de vivacidade.

Estes resultados podem então ser processados no seu retorno de chamada unificado para atualizar a UI ou prosseguir com o fluxo da sua aplicação.

***

## Configurações personalizadas

### Resumo da configuração do SDK

The SDK is configured via `CafSDKConfiguration`, which includes settings for:

* Ordem de fluxo (Ex.: etapas FaceLiveness e DocumentDetector).
* Personalização da UI (cores, instruções e imagens).
* Endpoints de proxy reverso e certificados de segurança.
* Parâmetros opcionais como `personId`.

### Configuração de proxy reverso

#### Para Face Liveness

Configure o endpoint WebSocket Seguro (WSS) e os certificados para o Face Liveness.

#### Requisitos:

* **Protocolo**: `wss://` (WebSocket Secure).
* **Certificados**: Base64-encoded SHA-256 hashes of the certificate's Subject Public Key Info (SPKI).

#### Configuração:

Todas as configurações de proxy reverso para o Face Liveness são definidas usando a estrutura `CafFaceLivenessConfig`.

#### **1- Definia a URL base**

Use a propriedade `livenessBaseUrl` para definir o endpoint WSS.\
**Exemplo:** `"wss://my.proxy.io/ws/"`

#### **2 - Defina os certificados**

Use a propriedade `certificates` para fornecer os hashes SPKI.\
**Exemplo:** `["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]`

#### Exemplo de código:

```swift
.setFaceLivenessConfig(CafFaceLivenessConfig(
    livenessBaseUrl: "wss://my.proxy.io/ws/",
    certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
        "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
        "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="]
))
```

### Proxy reverso de autenticação

Configure o endpoint HTTPS para solicitações de autenticação.

* **Requisito:** protocolo: `https://`
* **Configuração:** todas as configurações de proxy reverso para autenticação são definidas usando a estrutura `CafFaceLivenessConfig`.

#### **1- Defina a URL Base**

Use a propriedade `authBaseUrl` para definir o endpoint HTTPS.\
**Exemplo:** `"https://my.proxy.io/v1/faces/"`

#### Exemplo de código:

```swift
.setFaceLivenessConfig(CafFaceLivenessConfig(
    authBaseUrl: "https://my.proxy.io/v1/faces/"
))
```

***

## Estruturas de configuração

### Caf Face Liveness

Configuração para o fluxo Face Liveness.

| Property             | Type                           | Description                                                            | Default   |
| -------------------- | ------------------------------ | ---------------------------------------------------------------------- | --------- |
| `loadingEnabled`     | `Bool`                         | Enables/disables the loading screen.                                   | `true`    |
| `authBaseUrl`        | `String`                       | HTTPS URL for authentication requests. **Required for reverse proxy.** | `""`      |
| `livenessBaseUrl`    | `String`                       | WSS URL for FaceLiveness WebSocket. **Required for reverse proxy.**    | `""`      |
| `certificates`       | `[String]`                     | Base64-encoded SHA-256 SPKI hashes. **Required for WSS.**              | `[]`      |
| `instructionsConfig` | `CafInstructionsConfiguration` | Customize instructions screen (title, steps, images).                  | See below |

### Instruções de configuração

\
Personalize a tela de instruções do Face Liveness.

| Property          | Type        | Description                                                 | Default |
| ----------------- | ----------- | ----------------------------------------------------------- | ------- |
| `enabled`         | `Bool`      | Show/hide the instructions screen.                          | `true`  |
| `title`           | `String?`   | Header title (e.g., "Face Scan Instructions").              | `nil`   |
| `descriptionText` | `String?`   | Brief description (e.g., "Follow these steps").             | `nil`   |
| `steps`           | `[String]?` | Ordered list of instructions (e.g., \["Step 1", "Step 2"]). | `nil`   |
| `buttonTitle`     | `String?`   | Text for the confirmation button (e.g., "Start Scan").      | `nil`   |
| `headerImage`     | `UIImage?`  | Image displayed at the top of the screen.                   | `nil`   |

### Configuração de cores

Personalize a UI.

| Property          | Type     | Description                             | Format                     |
| ----------------- | -------- | --------------------------------------- | -------------------------- |
| `primaryColor`    | `String` | Primary buttons, highlights.            | Hex code (e.g., `#FF0000`) |
| `secondaryColor`  | `String` | Secondary elements, borders.            | Hex code                   |
| `contentColor`    | `String` | Text and icons.                         | Hex code                   |
| `backgroundColor` | `String` | Screen background.                      | Hex code                   |
| `mediumColor`     | `String` | Neutral elements (e.g., progress bars). | Hex code                   |

### Exemplo de códigos

#### Exemplo de código de configuração completa.

```swift
var facelivenessConfig = CafFaceLivenessConfig(
        instructionsConfig: CafInstructionsConfiguration(
            enabled: true,
            title: "Scan Your Face",
            descriptionText: "Follow these steps:",
            steps: ["Hold the phone steady", "Ensure good lighting"],
            buttonTitle: "Start Scan",
            headerImage: UIImage(named: "scan_icon")
        ), loadingEnabled: true,
        authBaseUrl: "https://my.proxy.io/v1/faces/",
        livenessBaseUrl: "wss://my.proxy.io/ws/",
        certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]
    )
```

***

### Mais informações

#### **Requisitos de certificado**

* Os certificados devem ser o **base64-encoded SHA-256 hash** do certificado Subject Public Key Info (SPKI).

#### **Aplicação de protocolo**

* A URL do **Face Liveness** deve usar `wss://`.
* A URL de **autenticação** deve usar `https://`.

#### **Valores padrão**

* `loadingEnabled` é **true** por padrão.
* `instructionsConfig.enabled` é **true** por padrão.

***

## Configurações personalizadas - Document Detector

O módulo **DocumentDetector** utiliza machine learning (via **TensorFlow Lite**) para detectar e validar documentos com segurança. Este módulo é altamente configurável, permitindo definir fluxos de documentos personalizados, telas de pré-visualização e configurações de captura manual.

Consulte: [DocumentDetector Configurations](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md).

## Configuração do Document Detector

O principal objeto de configuração para este módulo é o `CafDocumentDetectorConfig`, que oferece opções, como:

* **Fluxo:** um array de objetos `DocumentDetectorStep` para determinar a ordem e o tipo de capturas de documentos.
* **Personalização de layout:** defina a aparência da interface de captura usando a classe `DocumentDetectorLayout`.
* **Configurações de upload:** controle o formato do arquivo, compressão e tamanho máximo do arquivo com `CafUploadSettings`.
* **Opções de captura manual:** ative a captura manual, ajuste o tempo limite e configure detalhes da pré-visualização (como título, subtítulo, confirmação e rótulos de tentativa).
* **Configurações de proxy e timeout:** configure um proxy e ajuste o tempo limite de rede para uploads seguros de documentos (opcional)

#### Exemplo de código:

```swift
let documentConfig = CafDocumentDetectorConfig(
    flow: [/* Array of DocumentDetectorStep items */],
    layout: DocumentDetectorLayout(),
    uploadSettings: CafUploadSettings(enable: true),
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true
)
```

### Documentos disponíveis e personalização

O **CafSDK** fornece um conjunto de documentos pré-configurados (Ex.: `RG_FRONT`, `CNH_FRONT`, `PASSPORT`, etc.). Você pode **personalizar** esses documentos ou criar seus próprios fluxos ajustando as propriedades de cada `DocumentDetectorStep` e`CafDocument`

### Como funciona

Quando o `documentConfig` é definido na sua `CafSDKConfiguration`, o módulo Document Detector é automaticamente executado quando a sua posição na ordem de apresentação é atingida.

Após uma execução bem-sucedida, é disparado um evento `CafUnifiedEvent.Success`, que contém:

* **result:** um dicionário (`[String: Any]`) com os dados do documento capturado.
* **moduleName:** o identificador do módulo (Ex.: `"documentDetector"`).

Estes resultados então processados na sua resposta de chamada unificada, permitindo que você avance o fluxo ou armazene as informações capturadas, conforme necessário.

#### Exemplo de código:

```swift
sdkConfig.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .RG_FRONT)],
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true
))
```

Após a conclusão da captura e do processamento do documento, o módulo Document Detector dispara um evento `CafUnifiedEvent.Success` , que contém`moduleName` (Ex.: `"documentDetector"`) e um `result` com o documento capturado.

### Configurações personalizadas

Configure o SDK do Document Detector usando a estrutura `CafDocumentDetectorConfig` , que inclui:

* Etapas do fluxo de captura de documentos.
* Personalização do layout da UI.
* Mensagens de feedback
* Comportamento de upload
* Configurações de proxy

### Configurações principais

Propriedades do`CafDocumentDetectorConfig` .

| Property                     | Type                     | Description                                                   | Default          |
| ---------------------------- | ------------------------ | ------------------------------------------------------------- | ---------------- |
| `flow`                       | `[DocumentDetectorStep]` | Ordered list of document capture steps.                       | `[]`             |
| `layout`                     | `DocumentDetectorLayout` | UI customization (colors, buttons, fonts).                    | Default layout   |
| `uploadSettings`             | `CafUploadSettings`      | Controls document upload behavior.                            | `enable: false`  |
| `manualCaptureEnabled`       | `Bool`                   | Enables manual capture button.                                | `true`           |
| `manualCaptureTime`          | `TimeInterval`           | Timeout (seconds) for manual capture.                         | `45`             |
| `requestTimeout`             | `TimeInterval`           | HTTP request timeout.                                         | `60`             |
| `showPopup`                  | `Bool`                   | Shows/hides the initial instruction popup.                    | `true`           |
| `proxySettings`              | `CafProxySettings?`      | Reverse proxy configuration (host, port, auth).               | `nil`            |
| `previewShow`                | `Bool`                   | Enables post-capture preview screen.                          | `false`          |
| `previewTitle`               | `String?`                | Title text on preview screen.                                 | `nil`            |
| `previewSubtitle`            | `String?`                | Subtitle text on preview screen.                              | `nil`            |
| `previewConfirmLabel`        | `String?`                | Text for the confirmation button on preview.                  | `nil`            |
| `previewRetryLabel`          | `String?`                | Text for the retry button on preview.                         | `nil`            |
| `messageSettings`            | `CafMessageSettings`     | Customizable feedback messages.                               | Default messages |
| `enableMultiLanguage`        | `Bool`                   | Enables auto-translation of default messages.                 | `true`           |
| `allowedPassportCountryList` | `[CafCountryCodes]?`     | Whitelist of allowed passport countries (e.g., `.BR`, `.US`). | `nil`            |

### Personalização de layout

Propriedades do `DocumentDetectorLayout` .

| Property                 | Type                     | Description                                           | Default           |
| ------------------------ | ------------------------ | ----------------------------------------------------- | ----------------- |
| `closeButtonImage`       | `UIImage?`               | Image for the close button.                           | System default    |
| `closeButtonColor`       | `UIColor?`               | Color of the close button.                            | Primary color     |
| `closeButtonSize`        | `CGFloat?`               | Size (width/height) of the close button.              | `44`              |
| `closeButtonContentMode` | `UIView.ContentMode?`    | Content mode for the close button image.              | `.scaleAspectFit` |
| `uploadBackGroundColor`  | `UIColor`                | Background color during upload.                       | Primary color     |
| `previewBackGroundColor` | `UIColor`                | Background color for preview screen.                  | `.white`          |
| `primaryColor`           | `UIColor`                | Color for buttons/progress indicators.                | `#34D690` (green) |
| `feedbackColors`         | `DocumentFeedbackColors` | Colors for feedback overlays (default/error/success). | Predefined colors |
| `font`                   | `String?`                | Custom font name (e.g., "Avenir-Bold").               | System font       |

#### Exemplo de código:

```swift
let layout = DocumentDetectorLayout()
layout.closeButtonImage = UIImage(named: "close_icon")
layout.primaryColor = .blue
layout.font = "Helvetica-Bold"
layout.feedbackColors = DocumentFeedbackColors(
    defaultColor: .gray, 
    errorColor: .red, 
    successColor: .green
)
```

### Personalização de mensagens

Propriedades do`CafMessageSettings` .

| Property                    | Description                            | Default Value                     |
| --------------------------- | -------------------------------------- | --------------------------------- |
| `waitMessage`               | Shown during SDK initialization.       | "Aguarde" (Waiting)               |
| `fitTheDocumentMessage`     | Advises aligning document to the mask. | "Encaixe o documento na marcação" |
| `verifyingQualityMessage`   | Shown during quality check.            | "Verificando qualidade…"          |
| `lowQualityDocumentMessage` | Shown on capture failure.              | "Ops, tente novamente"            |
| `sensorLuminosityMessage`   | Low brightness warning.                | "Ambiente muito escuro"           |
| `sensorOrientationMessage`  | Device orientation warning.            | "Celular não está na horizontal"  |
| `aiScanDocumentMessage`     | Prompt to scan a document.             | "Escaneie um documento"           |
| `aiGetCloserMessage`        | Prompt to move closer.                 | "Se aproxime do documento"        |
| `aiCapturedMessage`         | Confirmation of successful capture.    | "Capturando o documento"          |

**Full list**: 20+ mensagens. Use `.set[MessageName](message: String)` para personalizar qualquer texto.

#### Exemplo de código:

```swift
let messages = CafMessageSettings()
        .setWaitMessage(message: "Please wait...")
        .setLowQualityDocumentMessage(message: "Poor quality. Retry.")
```

## Fluxo de captura de documento

Propriedades do `DocumentDetectorStep`.

| Property        | Type          | Description                                   | Required    |
| --------------- | ------------- | --------------------------------------------- | ----------- |
| `document`      | `CafDocument` | Document type to capture (e.g., `.RG_FRONT`). | Yes         |
| `stepLabel`     | `String?`     | Text shown at the bottom of the screen.       | No          |
| `illustration`  | `UIImage?`    | Image shown in the instruction popup.         | No          |
| `showStepLabel` | `Bool`        | Toggles visibility of the step label.         | No (`true`) |

#### Exemplo de código:

```swift
let step = DocumentDetectorStep(
    document: .RG_FRONT,
    stepLabel: "Front of ID",
    illustration: UIImage(named: "id_front_icon")
)
```

## Configurações de upload

Propriedades do `CafUploadSettings`.

| Property          | Type           | Description                               | Default        |
| ----------------- | -------------- | ----------------------------------------- | -------------- |
| `enable`          | `Bool`         | Enables document upload functionality.    | `false`        |
| `compress`        | `Bool`         | Compresses files before upload.           | `true`         |
| `fileFormats`     | `[FileFormat]` | Allowed formats: `.png`, `.jpeg`, `.pdf`. | All formats    |
| `maximumFileSize` | `Int`          | Max file size in KB.                      | `10000` (10MB) |

#### Exemplo de código:

```swift
let uploadSettings = CafUploadSettings(
    enable: true,
    fileFormats: [.jpeg, .pdf],
    maximumFileSize: 5000
)
```

## Configurações de Proxy

Propriedades do `CafProxySettings`.

| Property   | Type      | Description                     | Required |
| ---------- | --------- | ------------------------------- | -------- |
| `hostname` | `String`  | Proxy host (e.g., "proxy.com"). | Yes      |
| `port`     | `Int`     | Proxy port (e.g., `8080`).      | Yes      |
| `user`     | `String?` | Authentication username.        | No       |
| `password` | `String?` | Authentication password.        | No       |

#### Exemplo de código:

```swift
let proxy = CafProxySettings(hostname: "my.proxy.io", port: 443)
    .setAutentication(user: "admin", password: "secret")
```

## Documentos suportados no Document Detector

Use esses valores estáticos de `CafDocument`:

| Document Type | Description                                   |
| ------------- | --------------------------------------------- |
| `.RG_FRONT`   | Front of Brazilian ID (RG)                    |
| `.RG_BACK`    | Back of Brazilian ID (RG)                     |
| `.RG_FULL`    | Brazilian ID (opened, showing front and back) |
| `.CNH_FRONT`  | Front of Brazilian Driver’s License (CNH)     |
| `.CNH_BACK`   | Back of Brazilian Driver’s License (CNH)      |
| `.CNH_FULL`   | Brazilian Driver’s License (opened)           |
| `.CRLV`       | Brazilian Vehicle Registration (CRLV)         |
| `.RNE_FRONT`  | Front of Brazilian Foreigner ID (RNE)         |
| `.RNE_BACK`   | Back of Brazilian Foreigner ID (RNE)          |
| `.CTPS_FRONT` | Front of Brazilian Work Card (CTPS)           |
| `.CTPS_BACK`  | Back of Brazilian Work Card (CTPS)            |
| `.PASSPORT`   | Passport (any country)                        |
| `.ANY`        | Generic document (no specific validation)     |

#### Exemplo de código:

```swift
let layout = DocumentDetectorLayout()
layout.primaryColor = .blue
layout.closeButtonImage = UIImage(named: "close")

let config = CafDocumentDetectorConfig(
    flow: [
        DocumentDetectorStep(document: .RG_FRONT),
        DocumentDetectorStep(document: .RG_BACK)
    ],
    layout: layout,
    uploadSettings: CafUploadSettings(enable: true),
    proxySettings: CafProxySettings(hostname: "proxy.example.com", port: 8443),
    messageSettings: CafMessageSettings()
        .setWaitMessage(message: "Initializing...")
        .setLowQualityDocumentMessage(message: "Retry capture")
)


```

## Mais informações

Para mais detalhes e cenários avançados de uso, consulte os seguintes recursos:

* **GitHub Repository:** acesse o código fonte, rastreamento de problemas e notas de lançamento no repositório do [CafSDK GitHub repository](https://github.com/combateafraude/caf-ios-sdk).
* **Perguntas frequentes e Solução de problemas**: verifique nossa seção de FAQs para problemas comuns e dicas de solução de problemas.
* **Suporte**: para assistência adicional, entre em contato com nossa equipe de suporte ou participe do nosso fórum da comunidade de desenvolvedores.

Estamos atualizando continuamente a documentação à medida que novos recursos e melhorias são lançados. Mantenha seu acesso atualizado para futuras atualizações!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/ios/comecando-com-o-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.