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)

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.

Estrutura do XCFramework

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

1. 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/):

   seu-projeto/
     Frameworks/
       LivenessFacetecSDK-1.3.0-Release.xcframework
     SeuApp/
       SeuApp.xcodeproj
   
2. 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

3. 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:

   #!/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
   

   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.

4. Configurar Info.plist

   O SDK utiliza a câmera para a captura de liveness. Adicione ao Info.plist do app:

   <key>NSCameraUsageDescription</key>
   <string>Esta permissão é necessária para verificação de identidade por biometria facial.</string>
   

   Sem essa entrada o app vai crashar em runtime ao tentar iniciar a captura.

5. Confirmar Runpath Search Paths

   Em Build Settings → Runpath Search Paths do target, confirme:

   $(inherited)
   @executable_path/Frameworks
   
6. 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.

Estrutura recomendada no projeto

SeuApp/
├── Frameworks/
│   └── LivenessFacetecSDK-1.3.0-Release.xcframework
├── SeuApp.xcodeproj
└── Sources/
    └── ...

Próximos passos

Implementação

Inicialize o SDK e colete o resultado da verificação

Solução de problemas

Erros comuns ao adicionar o XCFramework e configurar o Xcode