> 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/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/start-sdk.md).

# Iniciar SDK

De **3.0.0** o fluxo tem três etapas: configure uma vez com `setup`, opcionalmente `pré-aquecer` a sessão, depois `startSDK` para exibir a tela de captura.

{% hint style="warning" %}
**Alterações que quebram na versão 3.0.0:** a configuração mudou de `startSDK` para `setup`. A antiga `startSDK(viewController:mobileToken:personId:…)` sobrecarga foi removida — chamadas existentes não vão compilar. Veja o [guia de migração](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/pages/3bff86622c51e8dc1de0f8af79879d76d2241435#v3.0.0).
{% endhint %}

## Configuração com setup

Chame `setup` antes de iniciar. Ele apenas armazena sua configuração — não faz nenhuma solicitação de rede e não apresenta nada.

| Parâmetro                                 | Obrigatório | Descrição                                                                                                                                                        |
| ----------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mobileToken: String`                     | Sim         | O `sessionToken` solicitado pelo seu backend para esta tentativa. Veja [Configuração do backend](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md) |
| `personId: String`                        | Sim         | Identificador do usuário                                                                                                                                         |
| `customLocalization: String?`             | Não         | Nome da tabela de strings para localização personalizada do iProov (por exemplo, "stringsBundle")                                                                |
| `customLocalizationBundle: Bundle?`       | Não         | Bundle que contém a tabela de strings personalizada (iProov `options.stringsBundle`)                                                                             |
| `uiCustomization: CerttaUiCustomization?` | Não         | Identidade visual para a tela de vivacidade (padrão: `nil`, sem personalização)                                                                                  |
| `environment: CafEnvironment`             | Não         | `.dev`, `.beta`, `.prod` (padrão: `.prod`)                                                                                                                       |
| `loading: Bool`                           | Não         | Exibir tela de carregamento do SDK (padrão: `true`)                                                                                                              |

Você pode chamar `setup` novamente para alterar qualquer valor — por exemplo, para trocar `personId` entre usuários. Fazer isso descarta uma sessão previamente pré-aquecida sempre que as credenciais ou o ambiente forem diferentes.

## Pré-aquecendo a sessão (opcional)

`prewarm()` faz a solicitação da sessão com antecedência para que `startSDK` possa abrir a câmera sem esperar pela rede. Chame-o em qualquer momento em que o usuário já esteja ocupado — uma tela de instruções, uma etapa de consentimento, um formulário — e a ida e volta se sobrepõe ao tempo de leitura dele, em vez de somar a ele.

```swift
sdk.setup(mobileToken: "your_mobile_token", personId: "your_person_id")
sdk.prewarm()                       // por exemplo, quando a tela de instruções aparece
// … o usuário lê as instruções …
sdk.startSDK(viewController: self)  // consome a sessão pré-aquecida
```

`prewarm()` retorna imediatamente e não informa nada: não tem manipulador de conclusão e nunca invoca o delegate. É seguro chamá-lo de qualquer thread e seguro chamá-lo mais de uma vez — enquanto uma solicitação estiver em andamento, ou enquanto uma sessão válida já estiver em cache, ele não faz nada em vez de solicitar uma segunda sessão.

**Pré-aquecer é sempre opcional e nunca pode interromper uma captura.** Se nenhuma sessão válida estiver disponível quando `startSDK` executa — porque o pré-aquecimento falhou, nunca foi chamado ou a sessão em cache não é mais utilizável — o SDK volta silenciosamente a solicitar a sessão inline, exatamente como fazia antes da 3.0.0.

Uma sessão pré-aquecida é descartada quando:

| Condição                             | Detalhe                                                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Ela tem mais de **90 segundos**      | Inicie a captura dentro dessa janela para se beneficiar do pré-aquecimento                                            |
| As credenciais ou o ambiente mudaram | Uma posterior `setup` com um `mobileToken`, `personId` ou `ambiente` a invalida                                       |
| O app foi enviado para segundo plano | A sessão em cache e as credenciais armazenadas são apagadas                                                           |
| Ela já foi usada                     | Cada sessão pré-aquecida é consumida por uma única `startSDK` chamada; chame `prewarm()` novamente para outra captura |

Dois comportamentos que valem notar ao integrar:

* **Não `loading()` / `loaded()` nenhum par é emitido para a solicitação da sessão no caminho pré-aquecido**, já que não há nada para aguardar. A partir de **3.1.0** também nenhum é emitido após a captura, porque o resultado é entregue imediatamente. Não confie em `loading()` como um sinal de que a captura começou.
* `prewarm()` armazena o token móvel e o ID da pessoa no keychain antes de emitir a solicitação, porque a solicitação é autenticada a partir do keychain. Eles são removidos se o pré-aquecimento falhar ou se o app for colocado em segundo plano.

## Chamar startSDK

`startSDK` exibe a tela de captura usando a configuração fornecida a `setup`. Ele recebe apenas o view controller apresentador. Chame-o na thread principal.

| Parâmetro                          | Obrigatório | Descrição                      |
| ---------------------------------- | ----------- | ------------------------------ |
| `viewController: UIViewController` | Sim         | O view controller apresentador |

Chamar `startSDK` sem um prévio `setup` não apresenta nada — ele informa `didFinishWithError(type: .invalidOptionsException, description:)` em vez disso. Veja [Referência de resultado](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/result-reference.md).

`startSDK` verifica o acesso à câmera antes de qualquer solicitação de rede. Se o usuário ainda não tiver decidido, o prompt do sistema é exibido; se o acesso for negado, o SDK informa `didFinishWithError(type: .cameraPermission, description:)`.

Chamar `startSDK` enquanto uma captura já estiver em andamento é ignorado — nada é apresentado e nenhum método do delegate é chamado.

{% hint style="warning" %}
**Alterações que quebram na versão 2.0.0:** `executeFaceAuth` foi removido. O SDK inicia uma transação assíncrona e retorna apenas `signedResponse`. Recupere o resultado final de vivacidade no seu backend.
{% endhint %}

### Exemplo

```swift
import CafFaceLivenessLite

class ViewController: UIViewController {
    private let sdk = CafFaceLivenessLiteSDK()

    override func viewDidLoad() {
        super.viewDidLoad()
        sdk.delegate = self

        sdk.setup(
            mobileToken: "your_mobile_token",
            personId: "your_person_id",
            customLocalization: nil,
            customLocalizationBundle: nil,
            environment: .prod,
            loading: true
        )
        sdk.prewarm()
    }

    func startLiteLiveness() {
        sdk.startSDK(viewController: self)
    }
}
```

### Localização personalizada com um bundle de framework

Quando `Localizable.strings` for enviado dentro de um framework (ou outro bundle que não seja o principal), passe tanto o nome da tabela quanto o bundle:

```swift
sdk.setup(
    mobileToken: "your_mobile_token",
    personId: "your_person_id",
    customLocalization: "Localizable",
    customLocalizationBundle: Bundle(for: CafFaceLivenessLiteSDK.self),
    environment: .prod,
    loading: true
)
sdk.startSDK(viewController: self)
```

Referência de localização: [Localização do iProov](https://github.com/iProov/ios/wiki/Localization)

### Personalização da interface

Para personalizar a tela de vivacidade — barra de cabeçalho, mensagem de orientação, área ao redor do oval do rosto e fonte — passe um `CerttaUiCustomization` por meio do `uiCustomization` parâmetro de `setup`. Disponível a partir de **2.1.0** e totalmente opcional. Veja [Personalização da interface](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/ui-customization.md).

## Próximos passos

* Trate os callbacks do delegate: [Ciclo de vida](/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/lifecycle.md) e [Tratamento de Erros](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/handling-errors.md).
* Encaminhe o `signedResponse` para o seu backend, que o valida e recupera o resultado: [Configuração do backend](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/start-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.