Installation

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

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:

$ nano ~/.netrc

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

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

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:

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:

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:

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:

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)) before resolving dependencies in Xcode.

Without valid credentials in .netrc, SPM package resolution may fail even if access to GitHub is correctly configured.

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

[email protected]:facephi-clienters/SDK-SdkPackage-SPM.git

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.

2. (Optional) Configure GitHub connection to Xcode with SSH

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.

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.

Add SSH key to the GitHub account

Follow steps 1 to 9 of Adding a new SSH key to your GitHub account - GitHub Docs.

Create Personal Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens.

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

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

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

4. Troubleshooting SPM

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:

rm -rf ~/Library/Developer/Xcode/DerivedData && rm -rf ~/Library/org.swift.swiftpm && rm -rf ~/Library/Caches/org.swift.swiftpm

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.

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

2. 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:

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

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. See also Improving Git protocol security on GitHub.

---

Support

If you have any questions or problems during installation, contact Facephi Technical Support.