> ## 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 (FaceTec) 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.
* Acesso ao arquivo `LivenessFacetecSDK-X.X.X-Release.xcframework` distribuído pela Valid.
* Um projeto iOS atendendo aos **Requisitos mínimos** abaixo.

## Requisitos mínimos

| Item                                     | Versão mínima  |
| ---------------------------------------- | -------------- |
| iOS Deployment Target                    | 14.0           |
| Xcode                                    | 15.0           |
| Swift                                    | 5.9            |
| Dispositivo para teste de fluxo completo | Físico (arm64) |

<Info>
  O XCFramework é um framework **dinâmico** que já embute o FaceTec SDK, o FingerprintPro e 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-1.3.0-Release.xcframework/
├── ios-arm64/                          ← device físico
│   └── LivenessFacetecSDK.framework/
│       ├── LivenessFacetecSDK
│       ├── Alamofire_Alamofire.bundle/  ← PrivacyInfo.xcprivacy da App Store
│       └── Frameworks/                 ← dependências embutidas
│           ├── FaceTecSDK.framework/
│           └── FingerprintPro.framework/
└── ios-arm64_x86_64-simulator/         ← simulador (arm64 + x86_64)
    └── LivenessFacetecSDK.framework/
        ├── LivenessFacetecSDK
        ├── Alamofire_Alamofire.bundle/
        └── Frameworks/
            ├── FaceTecSDK.framework/
            └── FingerprintPro.framework/
```

## Instalação

<Steps>
  <Step title="Obter o XCFramework">
    Solicite à equipe da Valid o arquivo `LivenessFacetecSDK-1.3.0-Release.xcframework`. Ele já contém o FaceTec SDK e todos os módulos internos do `LivenessFacetecSDK`.

    Copie o pacote para uma pasta dentro do projeto (por exemplo `Frameworks/`):

    ```text theme={"theme":"catppuccin-latte"}
    seu-projeto/
      Frameworks/
        LivenessFacetecSDK-1.3.0-Release.xcframework
      SeuApp/
        SeuApp.xcodeproj
    ```
  </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-1.3.0-Release.xcframework` | **Embed & Sign** |
  </Step>

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

    1. No target do app, acesse **Build Phases**.
    2. Clique em **+** → **New Run Script Phase**.
    3. Arraste a fase para rodar **após** o "Embed Frameworks".
    4. Cole o script abaixo:

    ```bash theme={"theme":"catppuccin-latte"}
    #!/bin/bash
    set -eo pipefail

    if [ -z "${EXPANDED_CODE_SIGN_IDENTITY}" ]; then
      echo "Skipping signing (no identity — Simulator build?)"
      exit 0
    fi

    NESTED_FW_DIR="${CODESIGNING_FOLDER_PATH}/Frameworks/LivenessFacetecSDK.framework/Frameworks"

    if [ ! -d "${NESTED_FW_DIR}" ]; then
      echo "warning: LivenessFacetecSDK nested Frameworks dir not found, skipping."
      exit 0
    fi

    for FW in "${NESTED_FW_DIR}"/*.framework; do
      [ -d "${FW}" ] || continue
      echo "Signing nested framework: ${FW##*/}"
      codesign --force --sign "${EXPANDED_CODE_SIGN_IDENTITY}" \
               --preserve-metadata=identifier,entitlements \
               "${FW}"
    done
    ```

    <Warning>
      Sem essa fase, o app crasha em device físico no primeiro `dlopen` dos frameworks aninhados. O simulador não exige essa etapa, mas mantê-la não causa problemas.
    </Warning>
  </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
    ```
  </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-1.3.0-Release.xcframework
├── SeuApp.xcodeproj
└── Sources/
    └── ...
```

## Próximos passos

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

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