> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/produtos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/sdk-mobile/ios-sdk/instalacion.md).

# Instalação

## O que inclui o SDK

O SDK Mobile é formado por um conjunto de **bibliotecas modulares (componentes)** que permitem construir uma solução biométrica adaptada a cada cliente.

***

## Distribuição das dependências

#### Configurar credenciais (`netrc`)

Os binários do SDK (tanto em **CocoaPods** quanto em **SPM**) são distribuídos a partir de **Artifactory**. Embora os pacotes SPM sejam resolvidos a partir de repositórios no GitHub, o Xcode baixa o binário empacotado como **ZIP** do Artifactory; por isso, é **obrigatório** dispor de credenciais válidas no arquivo `netrc` da sua máquina, **também se você integrar apenas por SPM**.

Solicite usuário e Token ao **equipe de suporte de Facephi**. O usuário deve ter permissões sobre os repositórios **`cocoa-pro-fphi`** e **`spm-pro-fphi`**.

Adicione as credenciais ao seu arquivo `netrc` executando no Terminal:

```sh
$ nano ~/.netrc
```

Inclua no final do arquivo o seguinte bloco (respeite a indentação com **dois espaços**):

```sh
machine facephicorp.jfrog.io
  login <USERNAME>
  password <TOKEN>
```

### CocoaPods

As bibliotecas (componentes) do SDK iOS são distribuídas por CocoaPods mediante o uso de um repositório privado do Artifactory.

#### 1. Preparar o ambiente

Para acessar o repositório privado da Facephi é necessário ter **CocoaPods** instalado na máquina.

Os componentes do SDK Mobile são distribuídos a partir de um repositório privado que requer credenciais, as quais você deve solicitar ao **equipe de suporte de Facephi**.

#### 2. Configurar acesso ao repositório privado

**Instale o Plugin de Artifactory**

```sh
sudo gem install cocoapods-art
```

> ⚠️ Em equipamentos com **chip M1**, podem ocorrer erros durante a instalação. Se isso acontecer, use o seguinte comando. Caso contrário, consulte a seção de incidentes no final desta página.
>
> `sudo arch -arm64 gem install ffi; sudo arch -arm64 gem install cocoapods-art`

Por fim, adicione o repositório que contém dependências privadas:

```sh
pod repo-art add cocoa-pro-fphi 
"https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi"
```

> Caso tenha problemas com a instalação, desinstale completamente o CocoaPods e todas as suas dependências para fazer uma instalação limpa.

#### 3. Adicionar repositório e dependências

No seu `Podfile`, adicione as seguintes configurações:

```sh
plugin 'cocoapods-art', :sources => [
  'cocoa-pro-fphi’
]

source 'https://cdn.cocoapods.org/'

target 'Example' do
  pod 'FPHISDKMainComponent', '~> $VERSION'

   post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXPANDED_CODE_SIGN_IDENTITY'] = ""
      config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
      config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
    end
  end
end
...
end

```

#### 4. Atualizar dependências

Antes de executar `pod install`, atualize o repositório local:

```sh
pod repo-art update cocoa-pro-fphi
```

Também é possível fazer uma *atualização limpa* excluindo previamente o repositório para garantir que não haja problemas de cache. Para isso, executamos:

```
pod repo-art remove cocoa-pro-fphi;
rm -rf $HOME/.cocoapods/repos/cocoa-pro-fphi; // $HOME usually refers to /Users/{username}
rm -rf $HOME/.cocoapods/repos-art/cocoa-pro-fphi;
```

E, por fim, adicionamos novamente o repositório privado:

```sh
pod repo-art add cocoa-pro-fphi 
"https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi"
```

### SPM

As bibliotecas (componentes) do SDK iOS são distribuídas por **Swift Package Manager (SPM)** por meio de repositórios no GitHub. Cada pacote faz referência a um **binário pré-compilado** empacotado em **ZIP** e hospedado em **Artifactory**; o Xcode o baixa durante a resolução de dependências.

Por isso, **independentemente de você usar HTTPS ou SSH** para resolver os pacotes no GitHub, **você deve ter configurado o arquivo `.netrc`** com credenciais de Artifactory (veja [Configurar credenciais (`netrc`)](#configurar-credenciales-netrc)) antes de resolver dependências no Xcode.

{% hint style="info" %}
Sem credenciais válidas em `.netrc`, a resolução de pacotes SPM pode falhar mesmo que o acesso ao GitHub esteja configurado corretamente.
{% endhint %}

#### 1. Preparar o ambiente

Os repositórios de pacotes SPM devem ser importados para o projeto na seção *Package Dependencies* do Xcode.

Os repositórios do SDK são **públicos no GitHub** e podem ser adicionados com **HTTPS** ou **SSH**. **Por padrão, use HTTPS**: não requer configuração adicional de chaves SSH nem vincular uma conta do GitHub no Xcode.

**Protocolo de acesso: HTTPS (recomendado por padrão) vs SSH (opcional)**

* **HTTPS** — Método padrão. Não requer configuração extra. Válido para os repositórios públicos do SDK.

```
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
```

* **SSH** — **Opcional.** Pode ser preferível em ambientes corporativos que já usem chaves SSH com o GitHub. Requer ter SSH configurado na sua conta (veja a seção 2).

```
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```

{% hint style="info" %}
O repositório *público* indica sua visibilidade no GitHub, não o protocolo de download. Você pode integrar o SDK por SPM usando **apenas HTTPS** sem completar a seção de SSH.
{% endhint %}

#### 2. (Opcional) Configurar conexão do GitHub com o Xcode via SSH <a href="#spm-ssh-opcional" id="spm-ssh-opcional"></a>

**Somente necessário se você for adicionar os pacotes SPM com URLs SSH** em vez de HTTPS. Se você usar HTTPS (recomendado por padrão), pode omitir esta seção.

Se optar por SSH, conecte o Xcode ao GitHub por meio de uma chave de criptografia SSH do tipo Ed25519.

**Gerar chave SSH**

Esta etapa é opcional e só precisa ser feita se você ainda NÃO tiver uma chave criada.

Seguimos os passos 1 a 3 de [Gerando uma nova chave SSH e adicionando-a ao ssh-agent - GitHub Docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key).

**Adicionar chave SSH ao diretório de chaves do equipamento**

Seguimos os passos 1 a 4 de [Gerando uma nova chave SSH e adicionando-a ao ssh-agent - GitHub Docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent).

**Adicionar chave SSH à conta do GitHub**

Seguimos os passos 1 a 9 de [Adicionando uma nova chave SSH à sua conta do GitHub - GitHub Docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account).

**Criar Token Pessoal**

1. Acessamos [Configurações do GitHub → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens/new).
2. Determinamos o tempo de expiração e as permissões que queremos conceder ao novo Token. Esta seção é muito importante, já que dependendo do uso que vamos dar aos nossos repositórios com XCode, precisaremos de mais ou menos permissões. **É importante conceder permissões estritamente para o que precisamos**.
3. Copiamos o Token gerado e o armazenamos com segurança em uma ferramenta do tipo *vault* como Keeper.

**Conectar XCode**

1. Abrimos XCode → Settings → Source Control
2. Adicionamos uma conta do GitHub
3. Nas credenciais, inserimos o nome da nossa conta e o Token que acabamos de gerar.
4. Aceitamos e, ao voltar para a visualização de configurações do XCode, clicamos na ![Info](https://facephicorporative.atlassian.net/gateway/api/emoji/327ed40d-1088-4122-8df3-ab0b3c942ddb/atlassian-info/path?scale=MDPI) sobre nossa nova conta vinculada.
5. Se você for usar URLs **SSH**, certifique-se de que SSH esteja selecionado e de que apareça a referência à chave configurada nas etapas anteriores. Se você usar **HTTPS**, esta etapa não se aplica.

#### 3. Como adicionar um SPM <a href="#como-anadir-un-spm-a-tu-proyecto" id="como-anadir-un-spm-a-tu-proyecto"></a>

Os SPMs são adicionados no nível do projeto, não no nível do target, como ocorre no CocoaPods.

Para isso, vamos à raiz da nossa aplicação → Project → Package Dependencies → +

<figure><img src="/files/42e880bfea8b58fe9032d5f50974f4900f998ce6" alt=""><figcaption></figcaption></figure>

Depois, copie a **URL HTTPS** do repositório remoto (método padrão):

```
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
```

Se preferir SSH e tiver concluído a seção 2, use a URL SSH equivalente (`git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git`).

<div align="left"><figure><img src="/files/a28e2332924ad6fe4116dcce9794fafce6d48957" alt="" width="480"><figcaption></figcaption></figure></div>

<figure><img src="https://media-cdn.atlassian.com/file/86700223-4823-4698-8e83-ef48334812d1/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=760" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/28fe1c91d2ff2786300646c6611f35d1ec1ab5ec" alt=""><figcaption></figcaption></figure>

***

O SPM contém e expõe *targets.* Estes targets são bibliotecas que devemos importar em um target do nosso projeto para poder usá-los. Para isso, vamos ao target que queremos que tenha essa dependência e adicionamos o módulo SPM desejado:

<figure><img src="https://media-cdn.atlassian.com/file/ccb52c10-4f48-4d46-9730-6f2a82771f74/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=760" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="https://media-cdn.atlassian.com/file/c8ea2e6c-ec22-4093-a02b-827e95664dfa/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=604" alt="" width="375"><figcaption></figcaption></figure>

#### 4. Solução de problemas do SPM <a href="#troubleshooting" id="troubleshooting"></a>

**Pontos-chave ao configurar no Xcode**

* **Dependency Rule:** ao adicionar cada pacote, configure a regra como **Up to Next Minor Version** (não *Up to Next Major Version*). Usar *Major* pode trazer versões com mudanças incompatíveis.
* **Frameworks, Libraries, and Embedded Content:** verifique se o target do seu app tem todos os módulos SPM adicionados. Se algum faltar, os `import` falharão mesmo que o SPM tenha baixado os pacotes corretamente.

**Erro 403 ao baixar binários do Artifactory (credenciais ou permissões)**

Se as credenciais de `.netrc` não estiverem configuradas, estiverem incorretas ou o usuário não tiver permissões sobre o repositório **`spm-pro-fphi`**, a resolução de pacotes SPM falha com um erro semelhante a:

```
failed downloading 'https://facephicorp.jfrog.io/artifactory/spm-pro-fphi/SDK/FPHISDKCoreComponent/2.8.1/core.zip' which is required by binary target 'core': badResponseStatusCode(403)
```

Verifique o seguinte:

* O bloco `machine facephicorp.jfrog.io` em `~/.netrc` está bem formado (indentado com **dois espaços**) e o **usuário** e **token** são válidos.
* Seu usuário do Artifactory tem permissões de leitura sobre **`spm-pro-fphi`** (e **`cocoa-pro-fphi`** se você também usar CocoaPods). Se não os tiver, solicite-os ao **equipe de suporte de Facephi**.
* Após corrigir as credenciais, limpe o cache do SPM e resolva as dependências novamente (veja *Problemas de cache* mais abaixo).

**Problemas de cache (SPM não resolve dependências ou o projeto não compila)**

Durante a Integração, o mais frequente são problemas de cache. Siga estas etapas **em ordem**:

1. Feche o projeto no Xcode.
2. Limpe o cache no Terminal. Execute o seguinte comando **em uma única linha**:

```sh
rm -rf ~/Library/Developer/Xcode/DerivedData && rm -rf ~/Library/org.swift.swiftpm && rm -rf ~/Library/Caches/org.swift.swiftpm
```

{% hint style="warning" %}
Os três comandos devem ser executados na mesma linha, unidos por `&&`. Se você os separar em várias linhas, o terminal pode não aplicar a limpeza completa.
{% endhint %}

3. Exclua o arquivo **`Package.resolved`**. Este arquivo guarda os SHA de commit que o SPM usa para baixar cada pacote; se estiver desatualizado, o SPM pode não resolver as dependências. Você pode encontrá-lo em:

   * Clique com o botão direito sobre o `.xcworkspace` (ou `.xcodeproj`) → *Mostrar conteúdo do pacote* → `xcshareddata` → `swiftpm` → `Package.resolved`.
   * Clique com o botão direito sobre o `.xcworkspace` (ou `.xcodeproj`) → clique com o botão direito sobre o `.xcworkspace` interno → *Mostrar conteúdo do pacote* → `xcshareddata` → `swiftpm` → `Package.resolved`.

   Exclua-o e deixe que o Xcode o regenere ao abrir o projeto novamente.
4. Abra o projeto e, no Xcode, execute *File → Packages → Reset Package Caches*.

**Os imports não resolvem, embora o SPM tenha baixado os pacotes**

Verifique se o **target** do seu app tenha todas as bibliotecas adicionadas em *Frameworks, Libraries, and Embedded Content*. É uma etapa que costuma ser esquecida ao migrar do CocoaPods ou ao trabalhar com workspaces.

**Os SPMs não são baixados e não consigo ver o erro**

Quando isso acontece, o XCode às vezes não nos mostra o erro. Para vê-lo, vamos ao terminal e executamos:

`$ xcodebuild -resolvePackageDependencies`

Com esse comando, conseguiremos ver o erro específico para solucioná-lo.

**Erro por chave RSA (somente se você usar SSH)**

Se você adicionar pacotes com URLs **SSH**, pode aparecer um erro semelhante a:

```
git@github.com:facephi/whatever_library.git: An unknown error occurred. ERROR: You're using an RSA key with SHA-1, which is no longer allowed.
```

Isso ocorre pelo uso de uma chave SSH com criptografia RSA, que o GitHub já não aceita. A solução é configurar o SSH com uma chave mais segura (recomenda-se Ed25519), seguindo o [item 2 opcional de SSH](#spm-ssh-opcional). Consulte também [Melhorando a segurança do protocolo Git no GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/).

***

## Suporte

Se tiver dúvidas ou problemas durante a instalação, entre em contato com o **Suporte Técnico de Facephi**.