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

# Instalação

> Adicione o LivenessIdentySDK (IDENTY Face AI) a um projeto iOS via Swift Package Registry

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) |

> [!NOTE]
>
> 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**.

> [!NOTE]
>
> 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](#dependência-opcional-ssid-real-via-biblioteca-de-fingerprint) se quiser um `ssid` real.

## Estrutura do XCFramework

```text theme={"theme":"catppuccin-latte"}
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.

## Instalação

**1. 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:

```text theme={"theme":"catppuccin-latte"}
machine <domínio-informado-pela-Valid>
login <seu-usuário>
password <seu-token>
```

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

```json theme={"theme":"catppuccin-latte"}
{ "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.

> [!NOTE]
>
> 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`).

**2. Adicionar o Swift Package**

Registre o escopo `valid` uma vez por máquina:

```bash theme={"theme":"catppuccin-latte"}
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`:

```swift theme={"theme":"catppuccin-latte"}
.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.

> [!WARNING]
>
> Use sempre `exact:` com a versão informada pela equipe da Valid. Não use `from:`, `upToNextMajor` nem outros ranges.

**3. 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.

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

```bash theme={"theme":"catppuccin-latte"}
#!/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}"
```

> [!WARNING]
>
> 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.

**4. 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:

```xml theme={"theme":"catppuccin-latte"}
<key>NSCameraUsageDescription</key>
<string>Esta permissão é necessária para verificação de identidade por biometria facial.</string>
```

> [!WARNING]
>
> 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:

```text theme={"theme":"catppuccin-latte"}
$(inherited)
@executable_path/Frameworks
```

**6. Validar iOS Deployment Target**

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

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

> [!WARNING]
>
> 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:

1. No Xcode, **File → Add Package Dependencies...**
2. Cole a URL: `https://github.com/shield-ai-technology/shield-ptr-spm.git`
3. 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.
4. Na tela de seleção de produto, marque **`ShieldPtr`** (único produto exposto pelo pacote) e adicione ao target do seu app.
5. Confirme que `ShieldPtr.framework` aparece em **Frameworks, Libraries, and Embedded Content** do seu target, com **Embed: Embed & Sign**.
6. 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](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/implementacao.md)) — `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).

```text theme={"theme":"catppuccin-latte"}
SeuApp/
├── SeuApp.xcodeproj         ← Package Dependencies referencia valid.liveness-identy-sdk
└── Sources/
    └── ...
```

## Próximos passos

> **[Implementação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/implementacao.md)**
>
> Inicialize o SDK e dispare uma verificação de vivacidade

> **[Solução de problemas](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/ios/troubleshooting.md)**
>
> Erros comuns ao resolver o pacote e configurar o Xcode


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.