> 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/sdks/sdk-mobile/ios-sdk/instalacion.md). # Instalación ## Qué incluye el SDK El SDK Mobile está formado por un conjunto de **librerías modulares (componentes)** que permiten construir una solución biométrica adaptada a cada cliente. *** ## Distribución de las dependencias #### Configurar credenciales (`netrc`) Los binarios del SDK (tanto en **CocoaPods** como en **SPM**) se distribuyen desde **Artifactory**. Aunque los paquetes SPM se resuelven desde repositorios en GitHub, Xcode descarga el binario empaquetado como **ZIP** desde Artifactory; por ello, es **obligatorio** disponer de credenciales válidas en el archivo `netrc` de tu máquina, **también si integras solo por SPM**. Solicita usuario y token al **equipo de soporte de Facephi**. El usuario debe tener permisos sobre los repositorios **`cocoa-pro-fphi`** y **`spm-pro-fphi`**. Añade las credenciales a tu archivo `netrc` ejecutando desde Terminal: ```sh $ nano ~/.netrc ``` Incluye al final del archivo el siguiente bloque (respeta el indentado con **dos espacios**): ```sh machine facephicorp.jfrog.io login password ``` ### Cocoapods Las librerías (componentes) del SDK iOS se distribuyen por cocoapods mediante el uso de un repositorio privado de Artifactory. #### 1. Preparar el entorno Para acceder al repositorio privado de Facephi es necesario tener **CocoaPods** instalado en la máquina. Los componentes del SDK Mobile se distribuyen desde un repositorio privado que requiere credenciales, las cuales debes solicitar al **equipo de soporte de Facephi**. #### 2. Configurar acceso al repositorio privado **Instala el plugin de Artifactory** ```sh sudo gem install cocoapods-art ``` > ⚠️ En equipos con **chip M1**, pueden producirse errores durante la instalación. Si ocurre, utiliza el siguiente comando. Si no, revisa la sección de incidencias al final de esta página. > > `sudo arch -arm64 gem install ffi; sudo arch -arm64 gem install cocoapods-art` Finalmente añade el repositorio que contiene dependencias privadas: ```sh pod repo-art add cocoa-pro-fphi "https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi" ``` > En caso de tener problemas con la instalación, desinstala completamente cocoapods y todas sus dependencias para hacer una instalación limpia. #### 4. Añadir repositorio y dependencias En tu `Podfile`, añade las siguientes configuraciones: ```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. Actualizar dependencias Antes de ejecutar `pod install`, actualiza el repositorio local: ```sh pod repo-art update cocoa-pro-fphi ``` También se puede hacer una *actualización limpia* borrando previamente el repositorio para asegurarnos de que no hay problemas de caché. Para ello, ejecutamos: ``` 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; ``` Y finalmente añadimos de nuevo el repositorio privado: ```sh pod repo-art add cocoa-pro-fphi "https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi" ``` ### SPM Las librerías (componentes) del SDK iOS se distribuyen por **Swift Package Manager (SPM)** mediante repositorios en GitHub. Cada paquete referencia un **binario precompilado** empaquetado en **ZIP** y hosteado en **Artifactory**; Xcode lo descarga durante la resolución de dependencias. Por eso, **independientemente de si uses HTTPS o SSH** para resolver los paquetes en GitHub, **debes tener configurado el archivo `.netrc`** con credenciales de Artifactory (véase [Configurar credenciales (`netrc`)](#configurar-credenciales-netrc)) antes de resolver dependencias en Xcode. {% hint style="info" %} Sin credenciales válidas en `.netrc`, la resolución de paquetes SPM puede fallar aunque el acceso a GitHub esté correctamente configurado. {% endhint %} #### 1. Preparar el entorno Los repositorios de paquetes SPM deben importarse al proyecto en el apartado *Package Dependencies* de Xcode. Los repositorios del SDK son **públicos en GitHub** y pueden añadirse con **HTTPS** o **SSH**. **Por defecto, usa HTTPS**: no requiere configuración adicional de claves SSH ni vincular una cuenta de GitHub en Xcode. **Protocolo de acceso: HTTPS (recomendado por defecto) vs SSH (opcional)** * **HTTPS** — Método por defecto. No requiere configuración extra. Válido para los repositorios públicos del SDK. ``` https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git ``` * **SSH** — **Opcional.** Puede ser preferible en entornos corporativos que ya usen claves SSH con GitHub. Requiere tener SSH configurado en tu cuenta (véase el apartado 2). ``` git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git ``` {% hint style="info" %} El repositorio *público* indica su visibilidad en GitHub, no el protocolo de descarga. Puedes integrar el SDK por SPM usando **solo HTTPS** sin completar el apartado de SSH. {% endhint %} #### 2. (Opcional) Configurar conexión de GitHub a Xcode con SSH **Solo necesario si vas a añadir los paquetes SPM con URLs SSH** en lugar de HTTPS. Si usas HTTPS (recomendado por defecto), puedes omitir este apartado. Si optas por SSH, conecta Xcode con GitHub mediante una clave de cifrado SSH de tipo Ed25519. **Generar clave SSH** Este paso es opcional y solo hay que hacerlo si NO tienes ya una clave creada. Seguimos los pasos 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). **Añadir clave SSH al directorio de claves del equipo** Seguimos los pasos 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). **Añadir clave SSH a la cuenta de GitHub** Seguimos los pasos 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). **Crear Token Personal** 1. Accedemos a [Configuración de GitHub → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens/new). 2. Determinamos el tiempo de expiración y los permisos que queremos dar al nuevo token. Este apartado es muy importante ya que dependiendo del uso que le vayamos a dar a nuestros repositorios con XCode necesitaremos más o menos permisos. **Es importante dar permisos estrictamente para lo que necesitamos**. 3. Copiamos el token generado y lo guardamos de forma segura en una herramienta de tipo *vault* como Keeper. **Conectar XCode** 1. Abrimos XCode → Settings → Source Control 2. Añadimos una cuenta de GitHub 3. En las credenciales introducimos el nombre de nuestra cuenta y el token que acabamos de generar. 4. Aceptamos y al volver a la vista de la configuración de XCode pulsamos en la ![Info](https://facephicorporative.atlassian.net/gateway/api/emoji/327ed40d-1088-4122-8df3-ab0b3c942ddb/atlassian-info/path?scale=MDPI) sobre nuestra nueva cuenta vinculada. 5. Si vas a usar URLs **SSH**, asegúrate de que aparezca seleccionado SSH y la referencia a la clave configurada en los pasos anteriores. Si usas **HTTPS**, este paso no aplica. #### 3. Cómo añadir un SPM Los SPMs se añaden a nivel de proyecto, no a nivel de target como sí ocurre en Cocoapods. Para hacerlo vamos a la raíz de nuestra aplicación → Project → Package Dependencies → +
Luego copia la **URL HTTPS** del repositorio remoto (método por defecto): ``` https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git ``` Si prefieres SSH y completaste el apartado 2, usa la URL SSH equivalente (`git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git`).
*** El SPM contiene y expone *targets.* Estos targets son librerías que debemos importar en un target de nuestro proyecto para poder usarlos. Para hacerlo, vamos al target que queramos que tenga esta dependencia y añadimos el módulo SPM deseado:
#### 4. Troubleshooting SPM **Puntos clave al configurar en Xcode** * **Dependency Rule:** al agregar cada paquete, configura la regla como **Up to Next Minor Version** (no *Up to Next Major Version*). Usar *Major* puede traer versiones con cambios incompatibles. * **Frameworks, Libraries, and Embedded Content:** verifica que el target de tu app tenga todos los módulos SPM añadidos. Si alguno falta, los `import` fallarán aunque SPM haya descargado los paquetes correctamente. **Error 403 al descargar binarios desde Artifactory (credenciales o permisos)** Si las credenciales de `.netrc` no están configuradas, son incorrectas o el usuario no tiene permisos sobre el repositorio **`spm-pro-fphi`**, la resolución de paquetes SPM falla con un error similar 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) ``` Comprueba lo siguiente: * El bloque `machine facephicorp.jfrog.io` en `~/.netrc` está bien formado (indentado con **dos espacios**) y el **usuario** y **token** son válidos. * Tu usuario de Artifactory tiene permisos de lectura sobre **`spm-pro-fphi`** (y **`cocoa-pro-fphi`** si también usas CocoaPods). Si no los tienes, solicítalos al **equipo de soporte de Facephi**. * Tras corregir las credenciales, limpia la caché de SPM y vuelve a resolver dependencias (véase *Problemas de caché* más abajo). **Problemas de caché (SPM no resuelve dependencias o el proyecto no compila)** Durante la integración, lo más frecuente son problemas de caché. Sigue estos pasos **en orden**: 1. Cierra el proyecto en Xcode. 2. Limpia la caché desde Terminal. Ejecuta el siguiente comando **en una sola línea**: ```sh rm -rf ~/Library/Developer/Xcode/DerivedData && rm -rf ~/Library/org.swift.swiftpm && rm -rf ~/Library/Caches/org.swift.swiftpm ``` {% hint style="warning" %} Los tres comandos deben ejecutarse en la misma línea, unidos por `&&`. Si los separas en varias líneas, la terminal puede no aplicar la limpieza completa. {% endhint %} 3. Elimina el archivo **`Package.resolved`**. Este archivo guarda los SHA de commit que SPM usa para descargar cada paquete; si está desactualizado, SPM puede no resolver las dependencias. Puedes encontrarlo en: * Clic derecho sobre el `.xcworkspace` (o `.xcodeproj`) → *Mostrar contenido del paquete* → `xcshareddata` → `swiftpm` → `Package.resolved`. * Clic derecho sobre el `.xcworkspace` (o `.xcodeproj`) → clic derecho sobre el `.xcworkspace` interno → *Mostrar contenido del paquete* → `xcshareddata` → `swiftpm` → `Package.resolved`. Elimínalo y deja que Xcode lo regenere al volver a abrir el proyecto. 4. Abre el proyecto y, en Xcode, ejecuta *File → Packages → Reset Package Caches*. **Los imports no resuelven aunque SPM descargó los paquetes** Revisa que el **target** de tu app tenga todas las librerías añadidas en *Frameworks, Libraries, and Embedded Content*. Es un paso que suele pasarse por alto al migrar desde CocoaPods o al trabajar con workspaces. **Los SPMs no se descargan y no puedo ver el error** Cuando esto ocurre, XCode a veces no nos dice el error. Para verlo, vamos a la terminal y ejecutamos: `$ xcodebuild -resolvePackageDependencies` Con ese comando sí que podremos ver el error concreto para darle solución. **Error por clave RSA (solo si usas SSH)** Si añades paquetes con URLs **SSH**, puede aparecer un error similar 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. ``` Ocurre por el uso de una clave SSH con cifrado RSA, que GitHub ya no admite. La solución pasa por configurar SSH con una clave más segura (se recomienda Ed25519), siguiendo el [apartado 2 opcional de SSH](#spm-ssh-opcional). Consulta también [Improving Git protocol security on GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/). *** ## Soporte Si tienes dudas o problemas durante la instalación, contacta con el **Soporte Técnico de Facephi**.