> 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/caf-sdk-pt-br/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 a 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 a 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 atenda aos requisitos mínimos:

| Requisito                        | Versão |
| -------------------------------- | ------ |
| **Target de implantação do iOS** | 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.

* **Token Móvel CAF**: válido [mobileToken CAF](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"),            // SDK completo
        .product(name: "DocumentDetector", package: "CafSDK"),    // Apenas DocumentDetector
        .product(name: "CafFaceLiveness", package: "CafSDK"),       // Apenas CafFaceLiveness
        .product(name: "IproovProvider", package: "CafSDK"),        // Provedor iProov opcional
        .product(name: "FaceTec2DProvider", package: "CafSDK")      // Provedor FaceTec 2D opcional
    ]
)
```

#### 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
# SDK completo
pod 'CafSDK'

# Apenas DocumentDetector
pod 'CafSDK/DocumentDetector'

# Apenas CafFaceLiveness
pod 'CafSDK/CafFaceLiveness'

# Provedor iProov opcional
pod 'CafSDK/IproovProvider'

# Provedor FaceTec 2D opcional
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:

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

#### Para Document Detector:

* **Descrição de uso da câmera** (`NSCameraUsageDescription`): necessário para capturar imagens de documentos.
* **Descrição de uso da biblioteca de fotos** (`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 Detector de Documentos

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 em que o fluxo de captura do CafSDK é configurado para 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
// Crie a configuração do SDK com os módulos desejados e configurações personalizadas
var sdkConfig = CafSDKConfiguration(
        presentationOrder: viewModel.presentationOrder
    ).setDocumentDetectorConfig(CafDocumentDetectorConfig(flow: [DocumentDetectorStep(document: .CNH_FRONT)])) // Exemplo de documento obrigatório
        .setFaceLivenessConfig(CafFaceLivenessConfig())

// Construa o SDK com os parâmetros necessários e um callback para eventos
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()

// Inicie a sessão do SDK
sdk.start()

// Exemplo de manipulador de evento unificado
private func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }
        switch event {
        case .loading:
            print("🔄 Carregando...")
        case .loaded:
            print("🔄 Carregado")
        case .success(let response):
            print("✅ Sucesso de \(response.moduleName):\n\(response.result)")
        case .error(let message):
            print("❌ Erro:\n\(message)")
        case .cancelled:
            print("⚠️ Cancelado")
        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:

* **Carregando:** indica que o SDK está em processamento.
* **Carregado:** notifica que todos os módulos estão prontos.
* **Sucesso (response: CafUnifiedResponse):** retorna o resultado após uma sessão bem-sucedida.
* **Erro (message: String):** fornece uma mensagem de erro caso algo dê errado.
* **Cancelado:** 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 `Sucesso` evento, incluindo:

* `moduleName:` identifica o módulo (Ex.: `"documentDetector"` ou `"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:**\
Se ocorrer um erro ou o usuário cancelar o processo:

* **Erro:** 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.
* **Cancelado:** 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:
        // Exibir um indicador de carregamento
        break
    case .loaded:
        // Atualizar a UI para mostrar que os módulos estão prontos
        break
    case .success(let response):
        // Processar a resposta bem-sucedida do módulo concluído
        print("Módulo: \(response.moduleName) Resultado: \(response.result)")
    case .error(let message):
        // Tratar o estado de erro (exibir um alerta, tentar novamente etc.)
        print("Erro: \(message)")
    case .cancelled:
        // Tratar o cancelamento de forma adequada
        break
    case .log(let level, let message):
        // Registrar mensagens internas para fins de depuração
        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 que 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):
        // Registrar mensagens para monitoramento detalhado do fluxo
        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) e [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 detalhadas de personalização, consulte: [Configurações de Face Liveness](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 (por meio de `CafInstructionsConfiguration`) que orientam a pessoa usuária.
* **Indicador de carregamento**: um sinalizador (`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: "Escaneie seu rosto",
        descriptionText: "Siga estas etapas:",
        steps: ["Segure o telefone firme", "Garanta boa iluminação"],
        buttonTitle: "Iniciar escaneamento",
        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

O SDK é configurado por meio de `CafSDKConfiguration`, que inclui configurações para:

* 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**: hashes SHA-256 codificados em Base64 do Subject Public Key Info (SPKI) do certificado.

#### Configuração:

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

#### **1 - Defina 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.

| Propriedade                    | Tipo                           | Descrição                                                                        | Padrão      |
| ------------------------------ | ------------------------------ | -------------------------------------------------------------------------------- | ----------- |
| `loadingEnabled`               | `Bool`                         | Ativa/desativa a tela de carregamento.                                           | `true`      |
| `authBaseUrl`                  | `String`                       | URL HTTPS para solicitações de autenticação. **Obrigatório para proxy reverso.** | `""`        |
| `livenessBaseUrl`              | `String`                       | URL WSS para o WebSocket do Face Liveness. **Obrigatório para proxy reverso.**   | `""`        |
| `certificates`                 | `[String]`                     | Hashes SPKI SHA-256 codificados em Base64. **Obrigatório para WSS.**             | `[]`        |
| `a configuração de instruções` | `CafInstructionsConfiguration` | Personalize a tela de instruções (título, etapas, imagens).                      | Veja abaixo |

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

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

| Propriedade       | Tipo        | Descrição                                                       | Padrão |
| ----------------- | ----------- | --------------------------------------------------------------- | ------ |
| `ativado`         | `Bool`      | Exibir/ocultar a tela de instruções.                            | `true` |
| `título`          | `String?`   | Título do cabeçalho (ex.: "Instruções de Escaneamento Facial"). | `nil`  |
| `descriptionText` | `String?`   | Breve descrição (ex.: "Siga estas etapas").                     | `nil`  |
| `steps`           | `[String]?` | Lista ordenada de instruções (ex.: \["Etapa 1", "Etapa 2"]).    | `nil`  |
| `buttonTitle`     | `String?`   | Texto do botão de confirmação (ex.: "Iniciar escaneamento").    | `nil`  |
| `headerImage`     | `UIImage?`  | Imagem exibida na parte superior da tela.                       | `nil`  |

### Configuração de cores

Personalize a UI.

| Propriedade      | Tipo     | Descrição                                     | Formato                             |
| ---------------- | -------- | --------------------------------------------- | ----------------------------------- |
| `primaryColor`   | `String` | Botões principais, destaques.                 | Código hexadecimal (ex.: `#FF0000`) |
| `secondaryColor` | `String` | Elementos secundários, bordas.                | Código hexadecimal                  |
| `contentColor`   | `String` | Textos e ícones.                              | Código hexadecimal                  |
| `cor de fundo`   | `String` | Fundo da tela.                                | Código hexadecimal                  |
| `mediumColor`    | `String` | Elementos neutros (ex.: barras de progresso). | Código hexadecimal                  |

### Exemplo de códigos

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

```swift
var facelivenessConfig = CafFaceLivenessConfig(
        instructionsConfig: CafInstructionsConfiguration(
            enabled: true,
            title: "Escaneie seu rosto",
            descriptionText: "Siga estas etapas:",
            steps: ["Segure o telefone firme", "Garanta boa iluminação"],
            buttonTitle: "Iniciar escaneamento",
            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 **hash SHA-256 codificado em Base64** do Subject Public Key Info (SPKI) do certificado.

#### **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 - Detector de Documentos

O módulo **DocumentDetector** utiliza machine learning (por meio de **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: [Configurações do DocumentDetector](https://github.com/combateafraude/public-docs/blob/docs-sdks/ios/broken-reference/README.md).

## Configuração do Detector de Documentos

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, a compressão e o 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 de itens DocumentDetectorStep */],
    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 são 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 `resultado` 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 de`CafDocumentDetectorConfig` .

| Propriedade                  | Tipo                     | Descrição                                                                            | Padrão           |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | ---------------- |
| `o fluxo`                    | `[DocumentDetectorStep]` | Lista ordenada de etapas de captura de documentos.                                   | `[]`             |
| `o layout`                   | `DocumentDetectorLayout` | Personalização da UI (cores, botões, fontes).                                        | Layout padrão    |
| `as configurações de upload` | `CafUploadSettings`      | Controla o comportamento de upload de documentos.                                    | `enable: false`  |
| `manualCaptureEnabled`       | `Bool`                   | Ativa o botão de captura manual.                                                     | `true`           |
| `manualCaptureTime`          | `TimeInterval`           | Tempo limite (em segundos) para captura manual.                                      | `45`             |
| `requestTimeout`             | `TimeInterval`           | Tempo limite da solicitação HTTP.                                                    | `60`             |
| `showPopup`                  | `Bool`                   | Mostra/oculta o popup de instrução inicial.                                          | `true`           |
| `proxySettings`              | `CafProxySettings?`      | Configuração de proxy reverso (host, porta, autenticação).                           | `nil`            |
| `previewShow`                | `Bool`                   | Ativa a tela de pré-visualização após a captura.                                     | `false`          |
| `previewTitle`               | `String?`                | Texto do título na tela de pré-visualização.                                         | `nil`            |
| `previewSubtitle`            | `String?`                | Texto do subtítulo na tela de pré-visualização.                                      | `nil`            |
| `previewConfirmLabel`        | `String?`                | Texto do botão de confirmação na pré-visualização.                                   | `nil`            |
| `previewRetryLabel`          | `String?`                | Texto do botão de tentar novamente na pré-visualização.                              | `nil`            |
| `messageSettings`            | `CafMessageSettings`     | Mensagens de feedback personalizáveis.                                               | Mensagens padrão |
| `enableMultiLanguage`        | `Bool`                   | Ativa a tradução automática das mensagens padrão.                                    | `true`           |
| `allowedPassportCountryList` | `[CafCountryCodes]?`     | Lista de permissões dos países de passaporte permitidos (por exemplo, `.BR`, `.US`). | `nil`            |

### Personalização de layout

Propriedades de `DocumentDetectorLayout` .

| Propriedade              | Tipo                     | Descrição                                                  | Padrão             |
| ------------------------ | ------------------------ | ---------------------------------------------------------- | ------------------ |
| `closeButtonImage`       | `UIImage?`               | Imagem para o botão de fechar.                             | Padrão do sistema  |
| `closeButtonColor`       | `UIColor?`               | Cor do botão de fechar.                                    | Cor primária       |
| `closeButtonSize`        | `CGFloat?`               | Tamanho (largura/altura) do botão de fechar.               | `44`               |
| `closeButtonContentMode` | `UIView.ContentMode?`    | Modo de conteúdo para a imagem do botão de fechar.         | `.scaleAspectFit`  |
| `uploadBackGroundColor`  | `UIColor`                | Cor de fundo durante o upload.                             | Cor primária       |
| `previewBackGroundColor` | `UIColor`                | Cor de fundo da tela de pré-visualização.                  | `.white`           |
| `primaryColor`           | `UIColor`                | Cor dos botões/indicadores de progresso.                   | `#34D690` (verde)  |
| `feedbackColors`         | `DocumentFeedbackColors` | Cores das sobreposições de feedback (padrão/erro/sucesso). | Cores predefinidas |
| `fonte`                  | `String?`                | Nome da fonte personalizada (ex.: "Avenir-Bold").          | Fonte do sistema   |

#### 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 de`CafMessageSettings` .

| Propriedade                 | Descrição                                    | Valor Padrão                      |
| --------------------------- | -------------------------------------------- | --------------------------------- |
| `waitMessage`               | Exibida durante a inicialização do SDK.      | "Aguarde" (aguardando)            |
| `fitTheDocumentMessage`     | Orienta a alinhar o documento com a máscara. | "Encaixe o documento na marcação" |
| `verifyingQualityMessage`   | Exibida durante a verificação de qualidade.  | "Verificando qualidade…"          |
| `lowQualityDocumentMessage` | Exibida na falha de captura.                 | "Ops, tente novamente"            |
| `sensorLuminosityMessage`   | Aviso de pouca iluminação.                   | "Ambiente muito escuro"           |
| `sensorOrientationMessage`  | Aviso de orientação do dispositivo.          | "Celular não está na horizontal"  |
| `aiScanDocumentMessage`     | Solicitação para escanear um documento.      | "Escaneie um documento"           |
| `aiGetCloserMessage`        | Solicitação para se aproximar.               | "Se aproxime do documento"        |
| `aiCapturedMessage`         | Confirmação de captura bem-sucedida.         | "Capturando o documento"          |

**Lista completa**: mais de 20 mensagens. Use `.set[MessageName](message: String)` para personalizar qualquer texto.

#### Exemplo de código:

```swift
let messages = CafMessageSettings()
        .setWaitMessage(message: "Aguarde...")
        .setLowQualityDocumentMessage(message: "Qualidade ruim. Tente novamente.")
```

## Fluxo de captura de documento

Propriedades de `DocumentDetectorStep`.

| Propriedade     | Tipo          | Descrição                                                     | Obrigatório  |
| --------------- | ------------- | ------------------------------------------------------------- | ------------ |
| `document`      | `CafDocument` | Tipo de documento a ser capturado (por exemplo, `.RG_FRONT`). | Sim          |
| `stepLabel`     | `String?`     | Texto exibido na parte inferior da tela.                      | Não          |
| `illustration`  | `UIImage?`    | Imagem exibida no popup de instrução.                         | Não          |
| `showStepLabel` | `Bool`        | Alterna a visibilidade do rótulo da etapa.                    | Não (`true`) |

#### Exemplo de código:

```swift
let step = DocumentDetectorStep(
    document: .RG_FRONT,
    stepLabel: "Frente do documento de identidade",
    illustration: UIImage(named: "id_front_icon")
)
```

## Configurações de upload

Propriedades de `CafUploadSettings`.

| Propriedade       | Tipo           | Descrição                                       | Padrão            |
| ----------------- | -------------- | ----------------------------------------------- | ----------------- |
| `ativar`          | `Bool`         | Ativa a funcionalidade de upload de documentos. | `false`           |
| `comprimir`       | `Bool`         | Compacta os arquivos antes do upload.           | `true`            |
| `fileFormats`     | `[FileFormat]` | Formatos permitidos: `.png`, `.jpeg`, `.pdf`.   | Todos os formatos |
| `maximumFileSize` | `Int`          | Tamanho máximo do arquivo em KB.                | `10000` (10MB)    |

#### Exemplo de código:

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

## Configurações de Proxy

Propriedades de `CafProxySettings`.

| Propriedade | Tipo      | Descrição                         | Obrigatório |
| ----------- | --------- | --------------------------------- | ----------- |
| `hostname`  | `String`  | Host do proxy (ex.: "proxy.com"). | Sim         |
| `port`      | `Int`     | Porta do proxy (ex.: `8080`).     | Sim         |
| `user`      | `String?` | Nome de usuário de autenticação.  | Não         |
| `password`  | `String?` | Senha de autenticação.            | Não         |

#### Exemplo de código:

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

## Documentos suportados no Detector de Documentos

Use esses valores estáticos de `CafDocument`:

| Tipo de documento | Descrição                                        |
| ----------------- | ------------------------------------------------ |
| `.RG_FRONT`       | Frente do RG brasileiro                          |
| `.RG_BACK`        | Verso do RG brasileiro                           |
| `.RG_FULL`        | RG brasileiro (aberto, mostrando frente e verso) |
| `.CNH_FRONT`      | Frente da CNH brasileira                         |
| `.CNH_BACK`       | Verso da CNH brasileira                          |
| `.CNH_FULL`       | CNH brasileira (aberta)                          |
| `.CRLV`           | CRLV brasileiro                                  |
| `.RNE_FRONT`      | Frente do RNE brasileiro                         |
| `.RNE_BACK`       | Verso do RNE brasileiro                          |
| `.CTPS_FRONT`     | Frente da CTPS brasileira                        |
| `.CTPS_BACK`      | Verso da CTPS brasileira                         |
| `.PASSPORT`       | Passaporte (qualquer país)                       |
| `.ANY`            | Documento genérico (sem validação específica)    |

#### 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: "Inicializando...")
        .setLowQualityDocumentMessage(message: "Tente capturar novamente")
)


```

## Mais informações

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

* **Repositório no GitHub:** acesse o código-fonte, o rastreamento de problemas e as notas de lançamento no repositório do [repositório GitHub do CafSDK](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/caf-sdk-pt-br/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.