Instalação

Integre o SDK Mobile da Facephi em seus aplicativos iOS para executar processos de verificação biométrica de forma rápida e segura.

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:

$ nano ~/.netrc

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

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

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

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:

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:

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:

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:

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)) antes de resolver dependências no Xcode.

Sem credenciais válidas em .netrc, a resolução de pacotes SPM pode falhar mesmo que o acesso ao GitHub esteja corretamente configurado.

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

[email protected]:facephi-clienters/SDK-SdkPackage-SPM.git

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.

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.

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.

Adicionar chave SSH à conta do GitHub

Seguimos os passos 1 a 9 de Adding a new SSH key to your GitHub account - GitHub Docs.

Criar Token Pessoal

1. Acessamos Configurações do GitHub → Developer Settings → Personal Access Tokens.

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 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 ([email protected]: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:

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

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.

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

2. 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:

[email protected]: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. Consulte também Improving Git protocol security on GitHub.

---

Suporte

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