Installation

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

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:

$ nano ~/.netrc

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

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

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:

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:

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:

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:

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

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

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

[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 only HTTPS without completing the SSH section.

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.

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.

Add SSH key to GitHub account

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

Create Personal Token

1. We go to GitHub Settings → Developer Settings → Personal Access Tokens.

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 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 ([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 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:

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

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.

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 internal → 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 libraries added in Frameworks, Libraries, and Embedded ContentThis 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:

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

---

Support

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