> 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/sdks/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** de Artifactory; por isso, é **obrigatório** ter credenciais válidas no arquivo `netrc` da sua máquina, **mesmo se você integrar apenas por SPM**. Solicite usuário e Token ao **time de Suporte Técnico da 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 password ``` ### CocoaPods As bibliotecas (componentes) do SDK iOS são distribuídas por CocoaPods por meio do 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 exige credenciais, as quais você deve solicitar ao **time de Suporte Técnico da Facephi**. #### 2. Configurar acesso ao repositório privado **Instale o Plugin do Artifactory** ```sh sudo gem install cocoapods-art ``` > ⚠️ Em máquinas com **chip M1**, podem ocorrer erros durante a instalação. Se isso acontecer, use o seguinte comando. Caso contrário, revise a seção de problemas 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. #### 4. Adicionar repositório e dependências Em 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 ``` #### 5. 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 garantirmos que não há 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 referencia 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 do 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 corretamente configurado. {% endhint %} #### 1. Preparar o ambiente Os repositórios de pacotes SPM devem ser importados para o projeto na seção *Dependências de Pacotes* 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 ao 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 preencher a seção de SSH. {% endhint %} #### 2. (Opcional) Configurar conexão do GitHub ao Xcode com SSH **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 [Generating a new SSH key and adding it to the 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 da equipe** Seguimos os passos 1 a 4 de [Generating a new SSH key and adding it to the 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 [Adding a new SSH key to your GitHub account - 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 dar ao novo Token. Esta seção é muito importante, pois, 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 guardamos com segurança em uma ferramenta do tipo *vault* como Keeper. **Conectar XCode** 1. Abrimos XCode → Configurações → Controle de código-fonte 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 tela de configuração 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 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 Os SPMs são adicionados no nível de projeto, não no nível de target como ocorre no CocoaPods. Para isso, vamos à raiz da nossa aplicação → Project → Package Dependencies → +
Em seguida, 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`).
*** O SPM contém e expõe *targets.* Esses 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:
#### 4. Solução de problemas do SPM **Pontos-chave ao configurar no Xcode** * **Regra de Dependência:** ao adicionar cada pacote, configure a regra como **Até a próxima versão minor** (não *Até a próxima versão major*). 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 estiver faltando, 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` en `~/.netrc` está bem formatado (com indentação de **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 **time de Suporte Técnico da Facephi**. * Depois de corrigir as credenciais, limpe o cache do SPM e volte a resolver as dependências (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 comum são problemas de cache. Siga estas etapas **em ordem**: 1. Feche o projeto no Xcode. 2. Limpe o cache pelo 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 armazena 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 reabrir o projeto. 4. Abra o projeto e, no Xcode, execute *Arquivo → Pacotes → Redefinir caches de pacotes*. **Os imports não resolvem mesmo que o SPM tenha baixado os pacotes** Verifique se o **target** do seu app tem todas as bibliotecas adicionadas em *Frameworks, Bibliotecas e Conteúdo Incorporado*. É uma etapa que costuma passar despercebida ao migrar do CocoaPods ou ao trabalhar com workspaces. **Os SPMs não são baixados e eu 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 não aceita mais. A solução é configurar o SSH com uma chave mais segura (recomenda-se Ed25519), seguindo o [seção opcional 2 de SSH](#spm-ssh-opcional). Consulte também [Improving Git protocol security on GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/). *** ## Suporte Se você tiver dúvidas ou problemas durante a instalação, entre em contato com o **Suporte Técnico da Facephi**.