> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Adicione o LivenessFacetecSDK v10 a um projeto iOS via XCFramework

Este guia mostra como adicionar o `LivenessFacetecSDK` — o pacote que embute o motor FaceTec — ao seu projeto iOS.

## Pré-requisitos

Antes de começar, garanta que você tem:

* Uma chave de API válida emitida pela Plataforma ID, usada **pelo seu backend** na criação da sessão — o app nunca a recebe.
* Acesso ao pacote distribuído pela Valid, que contém o `LivenessFacetecSDK-Release.xcframework` e o script `sign-nested-frameworks.sh`.
* O **Bundle Identifier** do seu app enviado à equipe da Valid para liberação na licença FaceTec.
* Um projeto iOS atendendo aos **Requisitos mínimos** abaixo.

<Warning>
  Sem a liberação do Bundle Identifier na licença FaceTec, a inicialização do SDK falha em runtime. Envie-o à equipe da Valid antes de testar em dispositivo físico.
</Warning>

## Requisitos mínimos

| Item                                     | Valor          |
| ---------------------------------------- | -------------- |
| iOS Deployment Target                    | 14.0           |
| Versão do `LivenessFacetecSDK`           | `2.0.0`        |
| FaceTec SDK embutido                     | `10.1.19`      |
| Shield embutido                          | `1.5.59`       |
| Dispositivo para teste de fluxo completo | Físico (arm64) |

<Info>
  O XCFramework é um framework **dinâmico** que já embute o FaceTec SDK e o Shield, com o Sentry vinculado estaticamente. **Nenhuma dependência SPM adicional** precisa ser declarada no projeto consumidor.
</Info>

## Estrutura do XCFramework

```text theme={"theme":"catppuccin-latte"}
LivenessFacetecSDK-Release.xcframework/
├── ios-arm64/                              ← device físico
│   └── LivenessFacetecSDK.framework/
│       ├── LivenessFacetecSDK
│       ├── PrivacyInfo.xcprivacy           ← privacy manifest da App Store
│       └── Frameworks/                     ← dependências dinâmicas embutidas
│           ├── FaceTecSDK.framework/        (10.1.19)
│           └── ShieldPtr.framework/         (1.5.59)
└── ios-arm64_x86_64-simulator/             ← simulador (arm64 + x86_64)
    └── LivenessFacetecSDK.framework/
        ├── LivenessFacetecSDK
        ├── PrivacyInfo.xcprivacy
        └── Frameworks/
            ├── FaceTecSDK.framework/
            └── ShieldPtr.framework/
```

Todos os módulos internos do SDK estão vinculados estaticamente ao binário `LivenessFacetecSDK` — só aparecem duas dependências dinâmicas. O **Sentry** também é estático e por isso não aparece na árvore.

<Info>
  Os **dSYMs não acompanham a entrega padrão**. Se precisar symbolicar um crash que envolva o SDK, solicite-os à equipe da Valid.
</Info>

<Warning>
  O fluxo de liveness **não executa no simulador**. A slice de simulador existe apenas para permitir que o app consumidor compile e vincule ao SDK sem erros. Veja [Limitação do simulador](/plataforma/liveness/facetec/v10/sdk/ios/troubleshooting#limitacao-do-simulador).
</Warning>

## Instalação

<Steps>
  <Step title="Obter o pacote de entrega">
    Solicite o pacote à equipe da Valid. Ele traz dois arquivos: o `.xcframework` e o script de build phase `sign-nested-frameworks.sh` (usado no passo seguinte). Copie os dois para dentro do projeto:

    ```text theme={"theme":"catppuccin-latte"}
    seu-projeto/
      Frameworks/
        LivenessFacetecSDK-Release.xcframework
      Scripts/
        sign-nested-frameworks.sh
      SeuApp/
        SeuApp.xcodeproj
    ```

    <Info>
      Versione os dois arquivos no seu repositório. O script precisa existir no projeto para a build phase do passo 3 conseguir referenciá-lo.
    </Info>
  </Step>

  <Step title="Adicionar o XCFramework ao target">
    1. Abra seu projeto no Xcode.
    2. Selecione o **target** do app consumidor.
    3. Vá em **General → Frameworks, Libraries, and Embedded Content**.
    4. Clique em **+** → **Add Other...** → **Add Files...** e selecione o `.xcframework`.
    5. Configure como **Embed & Sign**.

    | Framework                                | Embed            |
    | ---------------------------------------- | ---------------- |
    | `LivenessFacetecSDK-Release.xcframework` | **Embed & Sign** |

    <Info>
      **Não** adicione `FaceTecSDK` nem `ShieldPtr` separadamente — ambos já vêm embutidos dentro do XCFramework do SDK. Também não é preciso adicionar `sentry-cocoa` via SPM.
    </Info>
  </Step>

  <Step title="Adicionar build phase de re-assinatura">
    O Xcode **não re-assina automaticamente** os frameworks aninhados dentro do XCFramework (`FaceTecSDK.framework`, `ShieldPtr.framework`) — o "Embed Frameworks" assina só o framework externo. Sem essa etapa o app crasha no device com erro de assinatura de código.

    O script que faz isso é **entregue pela Valid** junto do `.xcframework`, como `sign-nested-frameworks.sh`. Você só precisa apontar uma build phase para ele:

    1. Confirme que `sign-nested-frameworks.sh` está no projeto (por exemplo em `Scripts/`) e é executável:

       ```bash theme={"theme":"catppuccin-latte"}
       chmod +x Scripts/sign-nested-frameworks.sh
       ```

    2. No target do app, acesse **Build Phases**.

    3. Clique em **+** → **New Run Script Phase**.

    4. Arraste a fase para rodar **após** o "Embed Frameworks".

    5. No corpo da fase, coloque apenas a chamada ao arquivo:

       ```bash theme={"theme":"catppuccin-latte"}
       "${SRCROOT}/Scripts/sign-nested-frameworks.sh"
       ```

    6. Em **Input Files** da fase, declare o caminho do script, para o Xcode não pular a fase em builds incrementais:

       ```text theme={"theme":"catppuccin-latte"}
       $(SRCROOT)/Scripts/sign-nested-frameworks.sh
       ```

    <Warning>
      **Não cole o conteúdo do script dentro da build phase.** Referenciando o arquivo, uma atualização do SDK substitui o script e a build phase passa a usar a versão nova automaticamente. Colado, o projeto fica preso a uma cópia antiga — e versões anteriores desse script re-assinavam apenas os frameworks aninhados, sem re-assinar o container, o que invalida o selo do `LivenessFacetecSDK.framework` e faz o processo morrer com `EXC_BREAKPOINT` durante a sessão, em device físico.
    </Warning>

    <Info>
      **O que a fase faz:** assina cada framework aninhado, re-assina o container `LivenessFacetecSDK.framework` (necessário porque a assinatura dos aninhados invalida o selo do container) e verifica o resultado, falhando a build se os selos ficarem inconsistentes — em vez de deixar o problema aparecer só no device.

      O simulador não exige essa etapa: o script detecta a ausência de identidade de assinatura e sai sem fazer nada, o que também cobre builds de CI sem assinatura.
    </Info>

    <Info>
      Se a fase falhar dizendo que **não encontrou** o `LivenessFacetecSDK.framework`, a causa é posicionamento: ela precisa rodar **depois** do "Embed Frameworks", e o XCFramework precisa estar em **General → Frameworks, Libraries, and Embedded Content** como **Embed & Sign**.
    </Info>

    <Info>
      Se o seu projeto usa `ENABLE_USER_SCRIPT_SANDBOXING = YES` (padrão em projetos novos), o `codesign` executado pela fase pode falhar por não conseguir acessar o keychain. Nesse caso, desabilite a opção **apenas no target do app**, não no nível do projeto.
    </Info>
  </Step>

  <Step title="Configurar Info.plist">
    O SDK utiliza a câmera para a captura de liveness. Adicione ao `Info.plist` do app:

    ```xml theme={"theme":"catppuccin-latte"}
    <key>NSCameraUsageDescription</key>
    <string>Esta permissão é necessária para verificação de identidade por biometria facial.</string>
    ```

    <Warning>
      Sem essa entrada o app vai crashar em runtime ao tentar iniciar a captura.
    </Warning>
  </Step>

  <Step title="Confirmar Runpath Search Paths">
    Em **Build Settings → Runpath Search Paths** do target, confirme:

    ```text theme={"theme":"catppuccin-latte"}
    $(inherited)
    @executable_path/Frameworks
    ```

    Isso permite ao dyld resolver o `LivenessFacetecSDK.framework` embutido no app. Os frameworks aninhados já carregam seu próprio `@loader_path/Frameworks` — nenhuma ação adicional é necessária para eles.
  </Step>

  <Step title="Validar iOS Deployment Target">
    Em **Build Settings → iOS Deployment Target**, defina o valor para **14.0** ou superior. Versões abaixo disso resultam em erros de link na build.
  </Step>
</Steps>

## Estrutura recomendada no projeto

```text theme={"theme":"catppuccin-latte"}
SeuApp/
├── Frameworks/
│   └── LivenessFacetecSDK-Release.xcframework
├── Scripts/
│   └── sign-nested-frameworks.sh   ← referenciado pela build phase
├── SeuApp.xcodeproj
└── Sources/
    └── ...
```

## Checklist pós-integração

Antes de considerar a integração concluída:

<Steps>
  <Step title="XCFramework embutido corretamente">
    `LivenessFacetecSDK-Release.xcframework` aparece em **Frameworks, Libraries, and Embedded Content** marcado como **Embed & Sign**.
  </Step>

  <Step title="Build phase de re-assinatura presente">
    A Run Script Phase aponta para `sign-nested-frameworks.sh` e roda **após** o "Embed Frameworks".
  </Step>

  <Step title="Info.plist e Build Settings">
    `NSCameraUsageDescription` presente no `Info.plist`; `@executable_path/Frameworks` em **Runpath Search Paths**; iOS Deployment Target ≥ **14.0**.
  </Step>

  <Step title="Relatório de privacidade da App Store atualizado">
    O Shield embutido declara **localização aproximada** e **identificador de dispositivo** como dados vinculados ao usuário. Reflita os dois no seu relatório de nutrição de privacidade — veja [Privacidade e App Store](/plataforma/liveness/facetec/v10/sdk/ios/troubleshooting#privacidade-e-app-store).
  </Step>

  <Step title="Inicialização no ciclo de vida do app">
    `LivenessFacetecSDKClient.shared.initialize(config:)` é chamado antes do primeiro uso, e `getSessionData()` é tratado via `switch` no `Result` (não lança) — um `ssid` vazio é aceitável.
  </Step>

  <Step title="Fluxo completo em dispositivo físico">
    Execute uma captura de ponta a ponta em device real. O simulador não roda sessão real, por limitação do vendor.
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/ios/implementacao">
    Inicialize o SDK e colete o resultado da verificação
  </Card>

  <Card title="Solução de problemas" icon="wrench" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/ios/troubleshooting">
    Erros comuns ao adicionar o XCFramework e configurar o Xcode
  </Card>
</CardGroup>