Skip to main content
Esta página lista os erros emitidos pelo 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

O IDENTY Face AI SDK não suporta execução real de liveness no simulador iOS — usa um binário stub. Testes de fluxo completo devem ser feitos em dispositivo físico.

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 pacote valid.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 ou swift 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 o LivenessIdentySDK.framework). Adicione o script descrito em Instalação.

Crash em runtime ao iniciar a captura

O Info.plist não declara NSCameraUsageDescription. Adicione:

Erro de deployment target

Garanta iOS Deployment Target ≥ 14.0 no projeto e no 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 adicionar shield-ptr-spm — veja Instalação. O XCFramework já embute dois PrivacyInfo.xcprivacy, detectados automaticamente pelo Xcode:
  • o do próprio SDK — declara NSPrivacyTracking = false e os tipos de dado Biometrics, DeviceID e CrashData, todos com Linked = false e Tracking = false;
  • o do Alamofire.
A declaração de privacidade na App Store Connect (e qualquer coleta própria do seu app) continua sendo responsabilidade do app consumidor no momento da submissão.

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