> 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/products/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/sdk-mobile/ios-sdk/instalacion.md).

# Installation

## What's included in the SDK

The SDK Mobile is made up of a set of **modular libraries (components)** that allow you to build a biometric solution tailored to each client.

***

## Dependency distribution

#### Configure credentials (`netrc`)

The SDK binaries (both in **CocoaPods** as well as in **SPM**) are distributed from **Artifactory**. Although SPM packages are resolved from repositories on GitHub, Xcode downloads the binary packaged 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 **Facephi 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 in Terminal:

```sh
$ nano ~/.netrc
```

Include the following block at the end of the file (respect indentation with **two spaces**):

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

### CocoaPods

The libraries (components) of the iOS SDK are distributed via CocoaPods through the use of a private Artifactory repository.

#### 1. Prepare the environment

To access Facephi's private repository, you need to have **CocoaPods** installed on the machine.

The SDK Mobile components are distributed from a private repository that requires credentials, which you must request from the **Facephi support team**.

#### 2. Configure access to the private repository

**Install the Artifactory plugin**

```sh
sudo gem install cocoapods-art
```

> ⚠️ On machines with **M1 chip**, errors may occur during installation. If that happens, use the following command. If not, 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.

#### 3. 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

```

#### 4. Update dependencies

Before running `pod install`, update the local repository:

```sh
pod repo-art update cocoa-pro-fphi
```

A *clean update* by deleting the repository beforehand to make sure there are no cache issues. To do this, 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 libraries (components) of the iOS SDK are distributed via **Swift Package Manager (SPM)** through repositories on GitHub. Each package references a **precompiled binary** packaged in **ZIP** and hosted on **Artifactory**; Xcode downloads it during dependency resolution.

Therefore, **regardless of whether you use HTTPS or SSH** to resolve the packages on GitHub, **you must have the file configured `.netrc`** 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 access to GitHub is correctly configured.
{% endhint %}

#### 1. Prepare the environment

SPM package repositories must be imported into the project under *Package Dependencies* in Xcode.

The SDK repositories are **public on GitHub** and can be added with **HTTPS** or **SSH**. **By default, use HTTPS**: it does not require additional SSH key setup or linking a GitHub account in Xcode.

**Access protocol: HTTPS (recommended by default) vs SSH (optional)**

* **HTTPS** — Default method. No extra setup required. Valid for the SDK public repositories.

```
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
```

* **SSH** — **Optional.** It 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 **HTTPS only** without completing the SSH section.
{% endhint %}

#### 2. (Optional) Configure GitHub connection to Xcode with SSH <a href="#spm-ssh-opcional" id="spm-ssh-opcional"></a>

**Only necessary if you are going to add 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 with GitHub using an SSH encryption key of type Ed25519.

**Generate SSH key**

This step is optional and only needs to be done if you do NOT already have a key created.

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**

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 the GitHub account**

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. 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 grant 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 only the permissions we strictly need**.
3. We copy the generated token and store it securely in a *vault* tool such as Keeper.

**Connect Xcode**

1. Open Xcode → Settings → Source Control
2. Add a GitHub account
3. In the credentials, enter our account name and the token we just generated.
4. Accept and, when returning to the Xcode settings view, click the ![Info](https://facephicorporative.atlassian.net/gateway/api/emoji/327ed40d-1088-4122-8df3-ab0b3c942ddb/atlassian-info/path?scale=MDPI) for our new linked account.
5. If you are going to use URLs **SSH**, make sure SSH is selected and that the reference to the key configured in the previous steps appears. If you use **HTTPS**, this step does not apply.

#### 3. How to add an SPM <a href="#como-anadir-un-spm-a-tu-proyecto" id="como-anadir-un-spm-a-tu-proyecto"></a>

SPMs are added at the project level, not at the target level as is the case in CocoaPods.

To do this, go to the root of our application → Project → Package Dependencies → +

<figure><img src="/files/3aef2f5335c292e9cfd5d869eb956527b2a6d243" alt=""><figcaption></figcaption></figure>

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

<div align="left"><figure><img src="/files/81e20815ee7c8b5383c81f08af0caa55b969312c" alt="" width="480"><figcaption></figcaption></figure></div>

<figure><img src="https://media-cdn.atlassian.com/file/86700223-4823-4698-8e83-ef48334812d1/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=760" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/e3e1cbfb8993069d46f135ab4fae9841f3363e22" alt=""><figcaption></figcaption></figure>

***

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 so, go to the target that you want to have this dependency and add the desired SPM module:

<figure><img src="https://media-cdn.atlassian.com/file/ccb52c10-4f48-4d46-9730-6f2a82771f74/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=760" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="https://media-cdn.atlassian.com/file/c8ea2e6c-ec22-4093-a02b-827e95664dfa/image/cdn?allowAnimated=true&#x26;client=2496a37b-bf8c-4ee3-a347-9deae0e25c51&#x26;collection=contentId-3812360243&#x26;height=125&#x26;max-age=2592000&#x26;mode=full-fit&#x26;source=mediaCard&#x26;token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyNDk2YTM3Yi1iZjhjLTRlZTMtYTM0Ny05ZGVhZTBlMjVjNTEiLCJhY2Nlc3MiOnsidXJuOmZpbGVzdG9yZTpjb2xsZWN0aW9uOmNvbnRlbnRJZC0zODEyMzYwMjQzIjpbInJlYWQiXX0sImV4cCI6MTc3MjcxMTA4NywibmJmIjoxNzcyNzA4MjA3LCJhYUlkIjoiNjA0N2E4N2Y1MTQ3MWMwMDZhYjJhZjI2IiwiaHR0cHM6Ly9pZC5hdGxhc3NpYW4uY29tL2FwcEFjY3JlZGl0ZWQiOmZhbHNlfQ.YsCtEHq02P38kdq_2HpB2BQ-9d9-GXXiE2TSoNYk9hk&#x26;width=604" alt="" width="375"><figcaption></figcaption></figure>

#### 4. Troubleshooting SPM <a href="#troubleshooting" id="troubleshooting"></a>

**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 in versions with 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 has downloaded the packages correctly.

**403 error downloading binaries from Artifactory (credentials or permissions)**

If the credentials for `.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` in `~/.netrc` is well formed (indented with **two spaces**) and the **user** 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 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 executed on the same line, joined by `&&`. If you split them across multiple lines, the terminal may not apply 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` inside → *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 the libraries added in *Frameworks, Libraries, and Embedded Content*. It is a step that is often overlooked when migrating from CocoaPods or working with workspaces.

**SPMs do not download and I can't see the error**

When this happens, Xcode sometimes does not tell us the error. To see it, go to the terminal and run:

`$ xcodebuild -resolvePackageDependencies`

With that command, we can 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 the following 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 because of 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 2](#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 any questions or problems during installation, contact **Facephi Technical Support**.