> 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

Integrate the Facephi Mobile SDK into your iOS applications to run biometric verification processes quickly and securely.

## What the SDK includes

The SDK Mobile consists of a set of **modular libraries (components)** that make it possible to build a biometric solution tailored to each customer.

***

## Dependency distribution

#### Configure credentials (`netrc`)

The SDK binaries (both for **CocoaPods** and **SPM**) are distributed from **Artifactory**. Although SPM packages are resolved from GitHub repositories, Xcode downloads the binary packaged as a **ZIP** from Artifactory; therefore, it is **mandatory** to have valid credentials in your machine's `netrc` file, **even if you integrate using SPM only**.

Request a username and token from the **Facephi support team**. The user must have permissions for the **`cocoa-pro-fphi`** and **`spm-pro-fphi`**.

Add the credentials to your `netrc` file by running this command in Terminal:

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

Add the following block at the end of the file (preserve the indentation with **two spaces**):

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

### CocoaPods

The iOS SDK libraries (components) are distributed via CocoaPods using a private Artifactory repository.

#### 1. Prepare the environment

To access Facephi's private repository, you need to have **CocoaPods** installed on your 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 computers with an **M1 chip**, errors may occur during installation. If this happens, use the following command. Otherwise, see the troubleshooting 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 the repository and dependencies

In your `Podfile`, add the following settings:

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

You can also perform a *clean update* by first deleting the repository to ensure 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;
```

Finally, 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 via **Swift Package Manager (SPM)** using GitHub repositories. Each package references a **precompiled binary** packaged as a **ZIP** and hosted on **Artifactory**; Xcode downloads it while resolving dependencies.

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

#### 1. Prepare the environment

SPM package repositories must be added to the project in Xcode's *Package Dependencies* section.

The SDK repositories are **public on GitHub** and can be added using **HTTPS** or **SSH**. **By default, use HTTPS**: it requires no additional SSH key configuration or linking a GitHub account in Xcode.

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

* **HTTPS** — Default method. No additional setup required. Works for the public SDK 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 for 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 using SPM with **HTTPS only** without completing the SSH section.
{% endhint %}

#### 2. (Optional) Configure the 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 using 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 an SSH key**

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

Follow steps 1 to 3 in [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 the SSH key to the computer's key directory**

Follow steps 1 to 4 in [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 the SSH key to your GitHub account**

Follow steps 1 to 9 in [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 a Personal Access Token**

1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens/new).
2. Set the expiration time and the permissions you want to grant to the new token. This section is very important, since the permissions you need will depend on how you plan to use your repositories with XCode. **It is important to grant only the permissions we strictly need**.
3. 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. Enter your account name and the token you just generated in the credentials.
4. Click Accept and, when you return to the XCode settings view, click ![Info](https://facephicorporative.atlassian.net/gateway/api/emoji/327ed40d-1088-4122-8df3-ab0b3c942ddb/atlassian-info/path?scale=MDPI) for your newly linked account.
5. If you are going to use **SSH**, make sure SSH is selected and that the key configured in the previous steps is referenced. 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 with CocoaPods.

To do this, go to the root of your app → Project → Package Dependencies → +

<figure><img src="https://865101184-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-0e6704d0f5d09ec245e5bcedcfb84fc51229dafb%2Fimage.png?alt=media" 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`).

<figure><img src="https://865101184-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-b69bfe862f6aab5f750c63030ebeff6639d29188%2Fimage.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

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

***

SPM contains and exposes *targets.* These targets are libraries that we need to import into a target in our project in order to use them. To do this, go to the target that should have this dependency and add the desired SPM module:

<figure><img src="https://865101184-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-1fdcfaeff69f35e5ff77018a9171116312f668f6%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://865101184-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-1d3cc4450701b444dbadb4dd1548b81d1578c5f6%2Fimage.png?alt=media" 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* may bring in versions with incompatible changes.
* **Frameworks, Libraries, and Embedded Content:** make sure that your app target has all the SPM modules added. If any are missing, the `import` statements will fail even if SPM downloaded the packages correctly.

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

If the credentials in `.netrc` are not configured, are incorrect, or the user does not have permission to access 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 correctly formatted (indented with **two spaces**) and the **username** and **token** are valid.
* Your Artifactory user has read access to **`spm-pro-fphi`** (and **`cocoa-pro-fphi`** if you also use CocoaPods). If you don't have access, request it 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 run on the same line, joined by `&&`. If you split them across multiple lines, the terminal may not perform the full cleanup.
{% endhint %}

3. Delete the **`Package.resolved`**. This file stores the commit SHAs that SPM uses to download each package; if it's out of date, SPM may not resolve the dependencies. You can find it here:

   * Right-click the `.xcworkspace` (or `.xcodeproj`) → *Show Package Contents* → `xcshareddata` → `swiftpm` → `Package.resolved`.
   * Right-click the `.xcworkspace` (or `.xcodeproj`) → right-click the `.xcworkspace` inner one → *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 don't resolve even though SPM downloaded the packages**

Check that your app's **target** has all the libraries added under *Frameworks, Libraries, and Embedded Content*. This step is often overlooked when migrating from CocoaPods or working with workspaces.

**SPM packages aren't downloaded, and I can't see the error**

When this happens, Xcode sometimes doesn't tell us what the error is. To find out, open the terminal and run:

`$ xcodebuild -resolvePackageDependencies`

This command will show the specific error so you can fix it.

**RSA key error (only if you use SSH)**

If you add packages using **SSH**URLs, you may see an error similar to:

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

This occurs because you're using an SSH key with RSA encryption, which GitHub no longer supports. To fix it, configure SSH with a more secure key (Ed25519 is recommended) by following the [optional section 2 of the SSH guide](#spm-ssh-opcional). Also see [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**.
