> 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-en/sdks/sdk-mobile/ios-sdk/instalacion.md). # Installation ## What the SDK includes The Mobile SDK is made up of a set of **modular libraries (components)** that allow you to build a biometric solution tailored to each customer. *** ## Dependency distribution #### Configure credentials (`netrc`) The SDK binaries (both in **CocoaPods** and in **SPM**) are distributed from **Artifactory**. Although SPM packages are resolved from repositories on GitHub, Xcode downloads the packaged binary as **ZIP** from Artifactory; therefore, it is **mandatory** to have valid credentials in the file `netrc` on your machine, **even if you integrate only via SPM**. Request the username and token from the **Facephi Technical Support team**. The user must have permissions on the repositories **`cocoa-pro-fphi`** and **`spm-pro-fphi`**. Add the credentials to your file `netrc` by running from Terminal: ```sh $ nano ~/.netrc ``` Include the following block at the end of the file (respect the indentation with **two spaces**): ```sh machine facephicorp.jfrog.io login password ``` ### CocoaPods The iOS SDK libraries (components) are distributed via cocoapods using a private Artifactory repository. #### 1. Prepare the environment To access the private Facephi repository, it is necessary to have **CocoaPods** installed on the machine. The Mobile SDK components are distributed from a private repository that requires credentials, which you must request from the **Facephi Technical Support team**. #### 2. Configure access to the private repository **Install the Artifactory plugin** ```sh sudo gem install cocoapods-art ``` > ⚠️ On machines with **M1 chip**, installation errors may occur. If this happens, use the following command. Otherwise, check the issues section at the end of this page. > > `sudo arch -arm64 gem install ffi; sudo arch -arm64 gem install cocoapods-art` Finally, add the repository that contains private dependencies: ```sh pod repo-art add cocoa-pro-fphi "https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi" ``` > If you have problems with the installation, completely uninstall cocoapods and all its dependencies to perform a clean installation. #### 4. Add repository and dependencies In your `Podfile`, add the following configurations: ```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. Update dependencies Before running `pod install`, update the local repository: ```sh pod repo-art update cocoa-pro-fphi ``` A *clean update* can also be done by deleting the repository beforehand to make sure there are no cache issues. To do this, we run: ``` 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; ``` And finally we add the private repository again: ```sh pod repo-art add cocoa-pro-fphi "https://facephicorp.jfrog.io/artifactory/api/pods/cocoa-pro-fphi" ``` ### SPM The iOS SDK libraries (components) are distributed by **Swift Package Manager (SPM)** through repositories on GitHub. Each package references a **precompiled binary** packaged in **ZIP** and hosted in **Artifactory**; Xcode downloads it during dependency resolution. Therefore, **regardless of whether you use HTTPS or SSH** to resolve packages on GitHub, **you must have the file `.netrc`** configured with Artifactory credentials (see [Configure credentials (`netrc`)](#configurar-credenciales-netrc)) before resolving dependencies in Xcode. {% hint style="info" %} Without valid credentials in `.netrc`, SPM package resolution may fail even if GitHub access is correctly configured. {% endhint %} #### 1. Prepare the environment SPM package repositories must be imported into the project in the *Package Dependencies* section of Xcode. The SDK repositories are **public on GitHub** and can be added with **HTTPS** or **SSH**. **By default, use HTTPS**: no additional SSH key configuration or linking a GitHub account in Xcode is required. **Access protocol: HTTPS (recommended by default) vs SSH (optional)** * **HTTPS** — Default method. No extra configuration required. Valid for the SDK's public repositories. ``` https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git ``` * **SSH** — **Optional.** May be preferable in corporate environments that already use SSH keys with GitHub. Requires SSH to be configured on your account (see section 2). ``` git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git ``` {% hint style="info" %} The repository *public* indicates its visibility on GitHub, not the download protocol. You can integrate the SDK via SPM using **only HTTPS** without completing the SSH section. {% endhint %} #### 2. (Optional) Configure GitHub connection to Xcode with SSH **Only necessary if you are going to add the SPM packages with SSH URLs** instead of HTTPS. If you use HTTPS (recommended by default), you can skip this section. If you choose SSH, connect Xcode to GitHub using an Ed25519 SSH encryption key. **Generate SSH key** This step is optional and only needs to be done if you do NOT already have a key created. We follow steps 1 to 3 of [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). **Add SSH key to the team's key directory** We follow steps 1 to 4 of [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). **Add SSH key to GitHub account** We follow steps 1 to 9 of [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). **Create Personal Token** 1. We go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens/new). 2. We determine the expiration time and the permissions we want to give the new token. This section is very important because depending on how we are going to use our repositories with Xcode we will need more or fewer permissions. **It is important to grant permissions strictly for what we need**. 3. We copy the generated token and store it securely in a tool such as *vault* like Keeper. **Connect Xcode** 1. We open Xcode → Settings → Source Control 2. We add a GitHub account 3. In the credentials, we enter our account name and the token we just generated. 4. We accept and when we return to the Xcode settings view, we click on the ![Info](https://facephicorporative.atlassian.net/gateway/api/emoji/327ed40d-1088-4122-8df3-ab0b3c942ddb/atlassian-info/path?scale=MDPI) above our newly linked account. 5. If you are going to use URLs **SSH**, make sure SSH appears selected and the reference to the key configured in the previous steps. If you use **HTTPS**, this step does not apply. #### 3. How to add an SPM SPMs are added at project level, not at target level as is the case in CocoaPods. To do this, go to the root of our application → Project → Package Dependencies → +
Then copy the **HTTPS URL** of the remote repository (default method): ``` https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git ``` If you prefer SSH and completed section 2, use the equivalent SSH URL (`git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git`).
*** The SPM contains and exposes *targets.* These targets are libraries that we must import into a target of our project in order to use them. To do this, we go to the target that we want to have this dependency and add the desired SPM module:
#### 4. SPM Troubleshooting **Key points when configuring in Xcode** * **Dependency Rule:** when adding each package, set the rule to **Up to Next Minor Version** (not *Up to Next Major Version*). Using *Major* can bring incompatible changes. * **Frameworks, Libraries, and Embedded Content:** verify that your app target has all the SPM modules added. If any are missing, the `import` will fail even if SPM downloaded the packages correctly. **403 Error downloading binaries from Artifactory (credentials or permissions)** If the credentials of `.netrc` are not configured, are incorrect, or the user does not have permissions on the repository **`spm-pro-fphi`**, SPM package resolution fails with an error similar to: ``` 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) ``` Check the following: * The block `machine facephicorp.jfrog.io` en `~/.netrc` is properly formatted (indented with **two spaces**) and the **username** and **token** are valid. * Your Artifactory user has read permissions on **`spm-pro-fphi`** (and **`cocoa-pro-fphi`** if you also use CocoaPods). If you do not have them, request them from the **Facephi Technical Support team**. * After correcting the credentials, clear the SPM cache and resolve dependencies again (see *Cache issues* below). **Cache issues (SPM does not resolve dependencies or the project does not build)** During integration, cache issues are the most common. Follow these steps **in order**: 1. Close the project in Xcode. 2. Clear the cache from Terminal. Run the following command **on a single line**: ```sh rm -rf ~/Library/Developer/Xcode/DerivedData && rm -rf ~/Library/org.swift.swiftpm && rm -rf ~/Library/Caches/org.swift.swiftpm ``` {% hint style="warning" %} The three commands must be run on the same line, joined by `&&`. If you separate them into multiple lines, the terminal may not perform the full cleanup. {% endhint %} 3. Delete the file **`Package.resolved`**. This file stores the commit SHAs that SPM uses to download each package; if it is outdated, SPM may not resolve the dependencies. You can find it in: * Right-click on the `.xcworkspace` (or `.xcodeproj`) → *Show Package Contents* → `xcshareddata` → `swiftpm` → `Package.resolved`. * Right-click on the `.xcworkspace` (or `.xcodeproj`) → right-click on the `.xcworkspace` internal → *Show Package Contents* → `xcshareddata` → `swiftpm` → `Package.resolved`. Delete it and let Xcode regenerate it when you reopen the project. 4. Open the project and, in Xcode, run *File → Packages → Reset Package Caches*. **Imports do not resolve even though SPM downloaded the packages** Check that the **target** of your app has all libraries added in *Frameworks, Libraries, and Embedded Content*This is a step that is often overlooked when migrating from CocoaPods or when working with workspaces. **SPMs do not download and I can't see the error** When this happens, Xcode sometimes doesn't tell us the error. To see it, go to the terminal and run: `$ xcodebuild -resolvePackageDependencies` With that command, we'll be able to see the specific error and fix it. **RSA key error (only if you use SSH)** If you add packages with URLs **SSH**, an error similar to this may appear: ``` 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. ``` It occurs due to using an SSH key with RSA encryption, which GitHub no longer supports. The solution is to configure SSH with a more secure key (Ed25519 is recommended), following the [optional SSH section](#spm-ssh-opcional). See also [Improving Git protocol security on GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/). *** ## Support If you have questions or problems during installation, contact **Facephi Technical Support**.