> ## 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. # Solução de problemas > Hierarquia de erros e diagnóstico do LivenessIdentySDK (IDENTY Face AI) no iOS 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:)`: ```swift theme={"theme":"catppuccin-latte"} public enum LivenessIdentySDKInitError: Error, LocalizedError { case identyInitializationFailed(String) case alreadyInitialized case provisioningFailed(String) } ``` | Erro | Quando acontece | Ação recomendada | | - | - | - | | `identyInitializationFailed` | Licença `.lic` ausente, duplicada ou inválida, ou o bundle ID do app não confere com o provisionado | Confirmar bundle ID e licença com a equipe Valid/IDENTY | | `alreadyInitialized` | `initialize()` foi chamado mais de uma vez no mesmo ciclo de vida | Verifique `isInitialized` antes de chamar. Para reinicializar, chame `stop()` primeiro | | `provisioningFailed` | Blob corrompido, chaves ausentes no build, ou falha na derivação das chaves internas | Verificar provisionamento de chaves com a equipe Valid | ## Erros de fluxo — `LivenessIdentySDKError` Emitidos via `LivenessIdentySDKLivenessState.error(LivenessIdentySDKError)`: ```swift theme={"theme":"catppuccin-latte"} public enum LivenessIdentySDKError: Error, LocalizedError { case captureError(String) case submitError(String) case networkError(String) case cancelled case unknown(String) } ``` | Erro | Quando acontece | Ação recomendada | | - | - | - | | `captureError` | Erro durante a captura reportado pelo IDENTY Face AI SDK. Na versão atual, também chegam por aqui o **fechamento da tela de captura pelo usuário** e a **permissão de câmera negada** | Apresente UI de "tentar novamente", tratando também a possibilidade de desistência do usuário. Se a câmera foi negada, oriente o usuário a liberá-la nas configurações | | `submitError` | Falha ao enviar os dados de captura para o backend, incluindo respostas HTTP 4xx/5xx | Repetir após reconectar. Se persistir, registre a mensagem e abra chamado | | `networkError` | Sem conectividade, timeout HTTP, ou `sessionToken` rejeitado | Cheque a rede do dispositivo (proxy/firewall) e a validade do `sessionToken` | | `cancelled` | Reservado para cancelamento pelo usuário — **não é emitido na versão atual** (veja [Limitações conhecidas](#limitações-conhecidas)) | Trate o caso para compatibilidade futura, mas não dependa dele para detectar desistência | | `unknown` | `startLivenessCheck` chamado antes de `initialize` (`"SDK not initialized. Call initialize() first."`), resposta inesperada do backend, ou erro inesperado | Confira a ordem `initialize` → `startLivenessCheck`. Se persistir, reporte com a mensagem para a equipe Valid | ### Exemplo de tratamento ```swift theme={"theme":"catppuccin-latte"} import LivenessIdentySDK func handleError(_ error: LivenessIdentySDKError) { let mensagem: String switch error { case .captureError(let detalhe): // Também pode indicar que o usuário fechou a captura ou negou a câmera mensagem = "A captura não foi concluída: \(detalhe)" case .submitError: mensagem = "Falha ao enviar. Verifique sua conexão." case .networkError: mensagem = "Sem conexão com a internet." case .cancelled: return // usuário cancelou case .unknown(let detalhe): mensagem = "Erro inesperado: \(detalhe)" @unknown default: mensagem = error.localizedDescription } mostrarAlerta(mensagem) } ``` ## Limitações conhecidas ### Simulador iOS > [!WARNING] > > 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/instalacao.md). ### 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/instalacao.md). ### 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/instalacao.md). ### Crash em runtime ao iniciar a captura O `Info.plist` não declara `NSCameraUsageDescription`. Adicione: ```xml theme={"theme":"catppuccin-latte"} NSCameraUsageDescription Esta permissão é necessária para verificação de identidade por biometria facial. ``` ### Erro de deployment target ```text theme={"theme":"catppuccin-latte"} 'LivenessIdentySDK' requires iOS 14.0 or later ``` 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/instalacao.md#dependência-opcional-ssid-real-via-biblioteca-de-fingerprint). | Dado coletado | Finalidade declarável | Coletor | | - | - | - | | Assinatura de dispositivo (`ssid`) | Prevenção de fraude | Biblioteca de fingerprint — só ativa se o app adicionar `shield-ptr-spm` | | Imagem biométrica (frame de câmera) | Autenticação / Prevenção de fraude | IDENTY Face AI SDK | | Dados de crash (stack traces) | Diagnóstico de app | Sentry (interno ao SDK) | 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/implementacao.md)** > > Volte para a referência de uso do SDK > **[Customização](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/customizacao.md)** > > Personalize o estilo da tela de captura This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.