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 do Artifactory; por isso, é obrigatório dispor de credenciais válidas no arquivo netrc da sua máquina, também se você integrar somente por SPM.

Solicite usuário e Token ao equipe de suporte 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 a partir do 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 no 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 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, confira 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:

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

Caso haja 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:

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:

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:

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 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 configurado corretamente.

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 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 GitHub. Requer ter SSH configurado em 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 somente HTTPS sem completar 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 usar HTTPS (recomendado por padrão), você 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ó deve 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.

Adicionar chave SSH ao diretório de chaves da equipe

Seguimos os passos 1 a 4 de Gerando uma nova chave SSH e adicionando-a ao ssh-agent - GitHub Docs.

Adicionar chave SSH à conta do GitHub

Seguimos os passos 1 a 9 de Adicionando uma nova chave SSH à sua conta do GitHub - GitHub Docs.

Criar Token Pessoal

Acessamos Configurações do GitHub → Configurações de Desenvolvedor → Tokens de Acesso Pessoal.
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 o XCode, precisaremos de mais ou menos permissões. É importante conceder permissões estritamente para o que precisamos.
Copiamos o Token gerado e o guardamos com segurança em uma ferramenta do tipo vault como o Keeper.

Conectar XCode

Abrimos XCode → Configurações → Controle de Código-fonte
Adicionamos uma conta do GitHub
Nas credenciais, inserimos o nome da nossa conta e o Token que acabamos de gerar.
Aceitamos e, ao voltar para a tela de configuração do XCode, clicamos na sobre nossa nova conta vinculada.
Se você for usar URLs SSH, certifique-se de que SSH apareça selecionado e a referência à chave configurada nos passos anteriores. Se usar HTTPS, esta etapa não se aplica.

3. Como adicionar um SPM

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

Para fazer isso, vamos à raiz da nossa aplicação → Projeto → Dependências de Pacotes → +

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 ([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 Menor (não Até a Próxima Versão Maior). Usar Major pode trazer versões com mudanças incompatíveis.
Frameworks, Bibliotecas e Conteúdo Incorporado: 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 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 usa CocoaPods). Se não as tiver, solicite-as ao equipe de suporte da Facephi.
Depois de corrigir as credenciais, limpe o cache do SPM e resolva novamente as dependências (veja Problemas de cache 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 estes passos em ordem:

Feche o projeto no Xcode.
Limpe o cache no 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.

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 reabrir o projeto.
Abra o projeto e, no Xcode, execute Arquivo → Pacotes → Redefinir caches de pacotes.

Os imports não resolvem, embora 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 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 resolvê-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.

Ocorre pelo uso de uma chave SSH com criptografia RSA, que o GitHub já não aceita. A solução passa por configurar o SSH com uma chave mais segura (recomenda-se Ed25519), seguindo o apartado opcional 2 de SSH. Consulte também Melhorando a segurança do protocolo Git no GitHub.

Suporte

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

AnterioriOS SDK

PróximoInicialização

Atualizado há 2 meses

O que inclui o SDK

Distribuição das dependências

Configurar credenciais (netrc)

CocoaPods

1. Preparar o ambiente

2. Configurar acesso ao repositório privado

3. Adicionar repositório e dependências

4. Atualizar dependências

SPM

1. Preparar o ambiente

2. (Opcional) Configurar conexão do GitHub ao Xcode com SSH

3. Como adicionar um SPM

4. Solução de problemas do SPM

Suporte

Configurar credenciais (`netrc`)