Instalação

Este guia mostra como adicionar o LivenessIdentySDK — o pacote que embute o motor IDENTY Face AI — ao seu projeto iOS.

Pré-requisitos

Antes de começar, garanta que você tem:

As credenciais (usuário e token) do Swift Package Registry da Valid, o domínio do registry e a versão do SDK a usar — todos informados pela equipe da Valid.
Uma licença IDENTY provisionada e atrelada ao bundle ID do seu app (veja a etapa de licença abaixo).
Um projeto iOS atendendo aos Requisitos mínimos abaixo.

Requisitos mínimos

Item	Versão mínima
iOS Deployment Target	14.0
Xcode	16.3
IDENTY Face AI embutido	`7.1.2`
Dispositivo para teste de fluxo completo	Físico (arm64)

O pacote valid.liveness-identy-sdk entrega o LivenessIdentySDK como um XCFramework dinâmico, que já embute os módulos internos do SDK, o IDENTY Face AI SDK e o Alamofire (vinculado estaticamente). O Sentry é declarado pelo próprio pacote como dependência SPM (Sentry-Dynamic) e resolvido automaticamente pelo Xcode — não adicione o sentry-cocoa por conta própria.

A coleta de assinatura de dispositivo via biblioteca de fingerprint é resolvida 100% internamente pelo SDK, mas o vínculo com o ShieldPtr é opcional (weak). Sem nenhuma ação sua, ssid vem vazio — nunca crasha, nunca bloqueia o fluxo. Veja a seção Dependência opcional: ssid real via biblioteca de fingerprint se quiser um ssid real.

Estrutura do XCFramework

LivenessIdentySDK.xcframework/
├── ios-arm64/                          ← device físico
│   └── LivenessIdentySDK.framework/
│       ├── LivenessIdentySDK
│       ├── PrivacyInfo.xcprivacy         ← privacy manifest do SDK
│       ├── Alamofire_Alamofire.bundle/   ← recursos do Alamofire (PrivacyInfo.xcprivacy)
│       ├── Identy_Identy.bundle/         ← licença IDENTY (.lic)
│       └── Frameworks/                   ← dependência dinâmica embutida
│           └── IdentyFace.framework/
└── ios-arm64_x86_64-simulator/         ← simulador (arm64 + x86_64)
    └── LivenessIdentySDK.framework/
        ├── LivenessIdentySDK
        ├── PrivacyInfo.xcprivacy
        ├── Alamofire_Alamofire.bundle/
        ├── Identy_Identy.bundle/
        └── Frameworks/
            └── IdentyFace.framework/

O Swift Package Manager baixa e gerencia esse XCFramework — você não copia nenhum arquivo para o projeto.

Configurar as credenciais do registry

O pacote é resolvido via um Swift Package Registry autenticado. Configure dois arquivos por máquina (e por runner de CI):~/.netrc — credencial do registry:

machine <domínio-informado-pela-Valid>
login <seu-usuário>
password <seu-token>

~/.swiftpm/configuration/registries.json — política para pacotes não assinados:

{ "security": { "default": { "signing": { "onUnsigned": "silentAllow" } } } }

Sem o ~/.netrc, a resolução falha com 401 Unauthorized. Sem o registries.json, o Xcode mostra um prompt de confirmação ao resolver o pacote.

Quando a resolução é feita pelo próprio Xcode em um projeto .xcodeproj, o Keychain do macOS tem prioridade sobre o ~/.netrc e a resolução pode falhar com 401 mesmo com o arquivo correto. Nesse caso: coloque também o registries.json em <SeuWorkspace>.xcworkspace/xcshareddata/swiftpm/configuration/registries.json e passe -packageAuthorizationProvider netrc ao xcodebuild (por exemplo, em xcodebuild -resolvePackageDependencies).

Adicionar o Swift Package

Registre o escopo valid uma vez por máquina:

swift package-registry set --global --scope valid "https://<domínio-informado-pela-Valid>/spm"
swift package-registry login "https://<domínio-informado-pela-Valid>/spm" \
  --username "<seu-usuário>" --password "<seu-token>"

Declare a dependência por identidade, não por URL — no Package.swift do seu projeto ou via File → Add Package Dependencies… no Xcode, informando o identificador valid.liveness-identy-sdk:

.package(id: "valid.liveness-identy-sdk", exact: "<versão-informada-pela-Valid>")

Na tela de seleção de produto (ou na declaração do target), marque LivenessIdentySDK e adicione ao target do seu app. O Xcode resolve o Sentry-Dynamic automaticamente.

Use sempre exact: com a versão informada pela equipe da Valid. Não use from:, upToNextMajor nem outros ranges.

Adicionar build phase de re-assinatura

O Xcode não re-assina automaticamente o framework aninhado dentro do XCFramework (IdentyFace.framework). Sem essa etapa o app vai crashar no device com erro de assinatura de código.Assinar o framework aninhado invalida a assinatura do LivenessIdentySDK.framework que o contém, por isso o script também re-assina o container no final.

No target do app, acesse Build Phases.
Clique em + → New Run Script Phase.
Arraste a fase para rodar após o “Embed Frameworks”.
Cole o script abaixo:

#!/bin/bash
set -eo pipefail

SIGN_IDENTY="${EXPANDED_CODE_SIGN_IDENTITY}"
if [ -z "${SIGN_IDENTY}" ]; then
  echo "Skipping signing (no identity — Simulator build?)"
  exit 0
fi

CONTAINER_FW="${CODESIGNING_FOLDER_PATH}/Frameworks/LivenessIdentySDK.framework"
NESTED_FW_DIR="${CONTAINER_FW}/Frameworks"

if [ ! -d "${NESTED_FW_DIR}" ]; then
  echo "warning: LivenessIdentySDK 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 "${SIGN_IDENTY}" \
           --preserve-metadata=identifier,entitlements \
           "${FW}"
done

# Assinar o framework aninhado invalida a assinatura do container —
# re-assine o LivenessIdentySDK.framework por último.
echo "Re-signing container: LivenessIdentySDK.framework"
codesign --force --sign "${SIGN_IDENTY}" \
         --preserve-metadata=identifier,entitlements \
         "${CONTAINER_FW}"

Sem essa fase, o app crasha em device físico no primeiro dlopen do framework aninhado. O simulador não exige essa etapa, mas mantê-la não causa problemas.

Configurar Info.plist

O SDK usa a câmera (via o IDENTY Face AI SDK) 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.

Confirmar Runpath Search Paths

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

$(inherited)
@executable_path/Frameworks

Validar iOS Deployment Target

Em Build Settings → iOS Deployment Target, defina o valor para 14.0 ou superior.

Confirmar a licença IDENTY (bundle ID)

A licença .lic embutida no XCFramework (Identy_Identy.bundle) é amarrada ao bundle ID do app consumidor informado à Valid/IDENTY no momento do provisionamento. Trocar o bundle ID do app invalida a licença em runtime (o SDK falha na inicialização), não em build.

Se a inicialização falhar com identyInitializationFailed e a mensagem “Nenhum arquivo .lic encontrado no bundle” ou “Mais de um arquivo .lic encontrado no bundle”, é sinal de empacotamento incorreto do XCFramework — reporte à equipe Valid.

Dependência opcional: `ssid` real via biblioteca de fingerprint

Não é preciso adicionar o sentry-cocoa — ele já vem como dependência do pacote valid.liveness-identy-sdk — nem os pacotes do IDENTY Face AI SDK, embutidos no XCFramework. O shield-ptr-spm não é dependência do pacote e nunca será — o vínculo com ele é opcional (weak). Sem essa dependência, ssid vem vazio, sem crash. Se você quiser um ssid real, siga os passos abaixo — nenhum código é necessário, só a adição do pacote:

No Xcode, File → Add Package Dependencies…
Cole a URL: https://github.com/shield-ai-technology/shield-ptr-spm.git
Em Dependency Rule, selecione Exact Version e digite 1.5.61 — não use “Up to Next Major”/“Up to Next Minor” nem nenhum range. O binário do ShieldPtr é resolvido por checksum pinado por versão exata; uma versão diferente da que o SDK foi weak-linkado não tem garantia de compatibilidade de ABI.
Na tela de seleção de produto, marque ShieldPtr (único produto exposto pelo pacote) e adicione ao target do seu app.
Confirme que ShieldPtr.framework aparece em Frameworks, Libraries, and Embedded Content do seu target, com Embed: Embed & Sign.
Build e rode normalmente — nenhum import, nenhuma conformidade de protocolo, nenhuma credencial a fornecer. O LivenessIdentySDK detecta a presença do ShieldPtr em runtime e passa a usar a implementação real automaticamente.

Você pode confirmar que funcionou chamando getSessionData() (veja Implementação) — sessionData.ssid deixa de vir vazio.

Estrutura recomendada no projeto

Nenhum arquivo do SDK vive no seu repositório — o Swift Package Manager cuida da resolução e do cache. O único registro é a declaração da dependência (no Package.swift, se o seu projeto for um pacote, ou no project.pbxproj/Package.resolved gerados pelo Xcode).

SeuApp/
├── SeuApp.xcodeproj         ← Package Dependencies referencia valid.liveness-identy-sdk
└── Sources/
    └── ...

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Instalação

Pré-requisitos

Requisitos mínimos

Estrutura do XCFramework

Instalação

Dependência opcional: `ssid` real via biblioteca de fingerprint

Estrutura recomendada no projeto

Próximos passos

Implementação

Solução de problemas

​Pré-requisitos

​Requisitos mínimos

​Estrutura do XCFramework

​Instalação

​Dependência opcional: ssid real via biblioteca de fingerprint

​Estrutura recomendada no projeto

​Próximos passos

Implementação

Solução de problemas

Pré-requisitos

Requisitos mínimos

Estrutura do XCFramework

Instalação

Dependência opcional: `ssid` real via biblioteca de fingerprint

Estrutura recomendada no projeto

Próximos passos