LivenessIdentySDK para iOS, limitações conhecidas, problemas comuns de build e dicas de diagnóstico.
Erros de inicialização — LivenessIdentySDKInitError
Lançados por LivenessIdentySDKClient.shared.initialize(config:):
Erros de fluxo — LivenessIdentySDKError
Emitidos via LivenessIdentySDKLivenessState.error(LivenessIdentySDKError):
Exemplo de tratamento
Limitações conhecidas
Simulador iOS
Cancelamento e permissão de câmera
Na versão atual, o SDK iOS não diferencia o fechamento da tela de captura pelo usuário nem a permissão de câmera negada: os dois chegam como.captureError(String), com a mensagem do vendor. O caso .cancelled existe na API, mas não é emitido. No Android, esses cenários têm erros dedicados (Cancelled, CameraPermissionDenied, CameraPermissionPermanentlyDenied).
Tier de backend fixo no artefato
A configuração Debug/Release do seu projeto Xcode não tem nenhum efeito sobre qual backend o SDK chama. O tier é definido no momento em que a Valid gera o SDK, e o pacotevalid.liveness-identy-sdk distribuído pelo registry é sempre o de produção. Se seu app precisar falar com um ambiente de homologação (ex.: QA), peça à equipe Valid um XCFramework gerado para esse ambiente — não há como alternar isso do seu lado.
Problemas comuns de build
Resolução do pacote falha com 401 Unauthorized
O ~/.netrc está ausente ou com credencial inválida/expirada para o domínio do registry. Confira machine/login/password e solicite uma credencial válida à equipe Valid. Se a resolução é feita pelo próprio Xcode, o Keychain pode estar tendo prioridade sobre o ~/.netrc — veja o passo de credenciais em Instalação.
Resolução do pacote falha com 404 Not Found
A identidade ou a versão do pacote estão incorretas. O identificador é case-sensitive e a versão não aceita prefixo v: confira id: "valid.liveness-identy-sdk" (tudo minúsculo) e a versão exata informada pela Valid.
O Xcode pede confirmação para um pacote não assinado
O~/.swiftpm/configuration/registries.json está ausente. Crie-o com onUnsigned: silentAllow, conforme Instalação.
Falha de checksum ou de extração ao resolver o pacote
Limpe o cache de pacotes (File → Packages → Reset Package Caches ouswift package purge-cache) e tente de novo. Se persistir, confirme com a equipe Valid a versão a usar e informe a mensagem de erro completa.
Crash no device com erro de code signing
Build phase de re-assinatura ausente ou incompleta (ela precisa re-assinar o framework aninhado e oLivenessIdentySDK.framework). Adicione o script descrito em Instalação.
Crash em runtime ao iniciar a captura
OInfo.plist não declara NSCameraUsageDescription. Adicione:
Erro de deployment target
ssid continua vazio mesmo após adicionar shield-ptr-spm
Confira, nessa ordem: (1) a Dependency Rule está como Exact Version 1.5.61, não um range; (2) ShieldPtr.framework está com Embed & Sign; (3) o pacote foi adicionado ao mesmo target que embeda o LivenessIdentySDK. Se os três estiverem corretos, a coleta pode ter falhado do lado da biblioteca de fingerprint — isso é best-effort por design, não é um bug a corrigir no app. Crie a sessão omitindo o campo ssid.
Privacidade e App Store
O SDK inclui internamente o IDENTY Face AI SDK (captura e processamento da imagem de câmera) e o Alamofire (vinculado estaticamente). O Sentry (crash reporting, hub privado, sem rastreamento de sessão) é resolvido como dependência do pacote. A biblioteca de fingerprint só é efetivamente usada se o app adicionarshield-ptr-spm — veja Instalação.
O XCFramework já embute dois
PrivacyInfo.xcprivacy, detectados automaticamente pelo Xcode:
- o do próprio SDK — declara
NSPrivacyTracking = falsee os tipos de dadoBiometrics,DeviceIDeCrashData, todos comLinked = falseeTracking = false; - o do Alamofire.
Verificação de saúde
Use este checklist quando o SDK não inicializar ou a verificação não completar:1
Confirme a versão do pacote
Verifique se o
valid.liveness-identy-sdk resolvido é a versão exact: informada pela equipe Valid.2
Confirme a build phase de re-assinatura
Sem ela, qualquer instalação em device físico crasha logo no
dlopen. O script precisa re-assinar o framework aninhado e o LivenessIdentySDK.framework.3
Confirme NSCameraUsageDescription
A captura é abortada pelo iOS se essa chave não estiver no
Info.plist.4
Confirme o bundle ID
O bundle ID do app precisa conferir com o provisionado para a licença IDENTY embutida.
5
Confirme conectividade
O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.
6
Teste em dispositivo físico
O simulador não executa liveness real por design (veja seção acima).
Próximos passos
Implementação
Volte para a referência de uso do SDK
Customização
Personalize o estilo da tela de captura