Skip to main content
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.
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.

​
Requisitos mínimos

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.

​
Estrutura do XCFramework

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.
Os dSYMs não acompanham a entrega padrão. Se precisar symbolicar um crash que envolva o SDK, solicite-os à equipe da Valid.
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.

​
Instalação

1

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:
Versione os dois arquivos no seu repositório. O script precisa existir no projeto para a build phase do passo 3 conseguir referenciá-lo.
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.
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.
3

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:
  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:
  6. Em Input Files da fase, declare o caminho do script, para o Xcode não pular a fase em builds incrementais:
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.
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.
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.
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.
4

Configurar Info.plist

O SDK utiliza a câmera para a captura de liveness. Adicione ao Info.plist do app:
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:
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.
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

​
Checklist pós-integração

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

XCFramework embutido corretamente

LivenessFacetecSDK-Release.xcframework aparece em Frameworks, Libraries, and Embedded Content marcado como Embed & Sign.
2

Build phase de re-assinatura presente

A Run Script Phase aponta para sign-nested-frameworks.sh e roda após o “Embed Frameworks”.
3

Info.plist e Build Settings

NSCameraUsageDescription presente no Info.plist; @executable_path/Frameworks em Runpath Search Paths; iOS Deployment Target ≥ 14.0.
4

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.
5

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.
6

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.

​
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