iOS SDK
Integrations guide
This page sets out step-by-step instructions for setting up your App Drop-in via the iOS SDK.
Prerequisites
- You need your
tenantId
provided by Fourthline. - Provide your implementation manager with the GitHub usernames and email addresses of your staff who need access to our repositories.
Operating system specifications:
- Minimum iOS version: 12
- MRZ detection in the document scanner requires minimum iOS 13.
Configuration
Age requirement
Configurable
You can dynamically configure the minimum client age requirement and the related checks during Identity Verification workflows.
Document data
Configurable
Discuss with your implementation manager what data to extract from ID document photos via optical character recognition (OCR):
Data type | Description |
---|---|
MRZ data | Document data is extracted from the MRZ only and is processed offline by the SDK. |
MRZ and VIZ data | For greater accuracy, document data is extracted from the MRZ and VIZ and processed by our AI agent in real time. |
Identity data
Configurable
If you want to receive a copy of the identity data gathered by the App Drop-in when it's uploaded to our backend (before case processing), let your implementation manager know.
Real-time feedback
Configurable
Agree with your implementation manager whether you want to enable real-time feedback. The SDKs send the document photos to our backend as soon as they are captured, where we assess the image quality and provide the client feedback in the UI in real time. This ensures higher-quality photos are ultimately uploaded, reduces sendbacks, and improves user experience.
Supported devices
Selfie video depth camera data
While recording the selfie video, Fourthline also collects depth camera data to help confirm liveness. This functionality uses Apple TrueDepth technology on every model later than iPhone X 2017, including iPhone 11 and higher, but excluding iPhones SE 2020 and SE 5G 2022.
Identity Verification
Setup
You can add the SDK to your project using Swift Package Manager, CocoaPods, or Carthage.
SDK version | Carthage Xcode Compatible .xcframework | Cocoa Xcode Compatible .xcframework | Minimum iOS version |
---|---|---|---|
2.28.0–latest | 14.3 and above | 14.3 and above | iOS 12 |
2.23.0–2.27.0 | 14.3 | 14.3 | iOS 12 |
2.15.1–2.22.0 | 14.1–14.2 | 14.1–14.2 | iOS 12 |
2.11.3–2.15.0 | 13.3.1–13.4 | 13.3.1–13.4 | iOS 12 |
2.8.0–2.11.2 | 13.0–13.1 | 13.0–13.1 | iOS 12 |
2.6.0–2.7.0 | 12.5 | 11.0–12.5 | iOS 12 |
1. To ensure clients grant camera and location permissions, in the Info.plist
file, add Privacy - Camera Usage Description
and Privacy - Location When In Use Usage Description
entries.
2. If configuring Document NFC, add Near Field Communication Tag Reading
capability to your app, containing the following values:
Tag-Specific Data Protocol (TAG)
Password Authenticated Connection Establishment (PACE)
Example entitlements file source code:
<dict>
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
<string>TAG</string>
<string>PACE</string>
</array>
</dict>
Then, to ensure clients grant NFC permissions, in the Info.plist
file, add Privacy - NFC Scan Usage Description
and Privacy - Location When In Use Usage Description
entries.
3. In the Info.plist
file, add an ISO7816 application identifiers for NFC Tag Reader Session
entry containing the following 2 keys:
A0000002471001
: Application ID for e-passportA00000045645444C2D3031
: Application ID for Dutch driving license
//1. Install Carthage on your machine. See GitHub – [Carthage](https://github.com/Carthage/Carthage) <img src="https://files.readme.io/f7f4159-Open_new_tab.svg" align="left"/>.
//2. Ensure the Carthage version is at least **0.38**. If installed via HomeBrew, you can check this with the following command: `brew list --versions carthage`
//3. Add **Cartfile** to the root of your project (or extend an existing one):
github "Fourthline-com/FourthlineSDK-iOS" == version.to.integrate
//4. Open a terminal and in your project root folder, run `carthage update --platform iOS --use-xcframeworks`.
//5. Authenticate in Fourthline's SDK repository using the credentials provided by your implementation manager.
//6. Go to the `Carthage/Build/iOS` folder, and then drag all the frameworks into the `Frameworks, libraries, and embedded content` section in Xcode.
//7. Set the `Embed` value to `Embed & sign`.
//1. Install CocoaPods on your machine. See CocoaPods – [Installation](https://guides.cocoapods.org/using/getting-started.html) <img src="https://files.readme.io/f7f4159-Open_new_tab.svg" align="left"/>.
//2. Add **Podfile** to the root of your project (or extend an existing one):
source 'https://github.com/Fourthline-com/FourthlineSDK-iOS-Specs.git' # to add our private pod
source 'https://github.com/CocoaPods/Specs.git' # to add other public pods
$version = 'version.to.integrate'
use_frameworks!
platform :ios, '12.0'
target 'YourTargetName' do
pod 'FourthlineSDK', $version
end
// Minimum version: v2.30.0
//1. In Xcode, go to **File** > **Add packages**.
//2. Enter the following URL: `https://github.com/Fourthline-com/FourthlineSDK-iOS`
//3. Select and import the following frameworks: `FourthlineCore`, `FourthlineVision`, `FourthlineNFC`, `FourthlineKYC`, `FourthlineSDK`.
Error handling
You need to handle the following error values:
Name | Description |
---|---|
invalidValidationCode | The validation code for the SDK session is invalid. Action: Get a new validation code. |
invalidWorkflowStatus | The status of the workflow is invalid, e.g. because the modules were completed successfully or with an error. |
clientRejected | The client isn't eligible for the Identity Verification workflow. You can't retry. |
canceled | The client canceled the workflow. |
unexpected | An unexpected error occurred. Action: Contact your implementation manager immediately. |
configurationNotSupported | The workflow created with the validation code isn't supported. Action: Consider updating to the latest SDK version. |
moduleError | The client encountered an error in a workflow module. |
Identity Verification | |
• PersonNotAdult : The client is underage. | |
• NationalityNotSupported : The client's nationality isn't supported. | |
• IssuingCountryNotSupported : The ID document issuing country isn't supported. | |
• DocumentExpired : The ID document has expired. | |
• DocumentTypeNotSupported : The ID document type isn't supported. | |
Bank Account Verification | |
• Failed : An unexpected generic error occurred. | |
• KycRequired : The client must first pass Identity Verification. | |
Qualified Electronic Signature | |
• TooManyResendOtpAttempts : The one-time passcode was resent to the client too many times. | |
• TooManyAuthorizationAttempts : The client tried to approve the documents to sign too many times. | |
• KycRequired : The client must first pass Identity Verification. |
Testing
To view a mock version, launch the various modules using the following mock validation codes:
Product | Mock validation code |
---|---|
Identity Verification | IDV |
Qualified Electronic Signature module | QES |
Bank Account Verification module | BAV |
Combinations | IDVandBAV IDVandQES IDVandBAVandQES IDVandQESandBAV |
Example code:
import FourthlineSDK
override func viewDidLoad() {
super.viewDidLoad()
let customization = WorkflowConfig(
networkEnvironment: .mock
)
Orca.workflow(validationCode: "A1B2C3D4")
.configure(with: customization)
.present(completionBlock: { _ in
})
}
Bank Account Verification
If your workflow includes Bank Account Verification, this module redirects to the Web SDK.
To redirect the client back to your app after completing the module in the web browser, you need to register a URL scheme.
For instructions, see Apple – Register your URL scheme.
Client Authentication
Setup
To ensure the client has granted camera and location permissions, in the Info.plist file, add Privacy - Camera Usage Description
and Privacy - Location When In Use Usage Description
entries.
import FourthlineSDK
override func viewDidLoad() {
super.viewDidLoad()
var flavor = OrcaFlavor()
// Configure the colors
var palette = OrcaPalette()
palette.primary = UIColor(red: 82.0 / 255.0, green: 30.0 / 255.0, blue: 135.0 / 255.0, alpha: 1)
var colors = OrcaColors(colorPalette: palette)
flavor.colors = colors
// Configure the language
flavor.localization.fixedLanguage = .fr
let customization = CcrCustomizationConfig(flavor: flavor)
Orca.ccr
.customize(with: customization)
.present { [weak self] result in
switch result {
case let .failure(error):
self?.handleCcrError(error)
case let .success(ccrResult):
/// Upload the CcrResult...
break
}
}
}
Error handling
You need to handle the following error values:
Error | Description |
---|---|
Canceled | The client canceled the flow. |
Unexpected | An unexpected error occurred. Immediately report this issue along with the message code. |
Testing
Example code:
import FourthlineSDK
override func viewDidLoad() {
super.viewDidLoad()
Orca.ccr.testMe()
}
Document Authentication
Setup
1. To ensure the client has granted camera permissions, in the Info.plist file, add a Privacy - Camera Usage Description
entry.
2. The Document Authentication module requires a CdrConfig
containing a list of supported countries.
UI customization
To customize the UI, create an OrcaFlavor
object.
For more information, see App UI Customization.
import FourthlineSDK
override func viewDidLoad() {
super.viewDidLoad()
// Create the Cdr Configuration
let cdrConfig = CdrConfig(supportedCountries: dataSource.supportedCountries)
// Customize the Cdr flavor
var flavor = OrcaFlavor()
// Configure the colors
var palette = OrcaPalette()
palette.primary = UIColor(red: 82.0 / 255.0, green: 30.0 / 255.0, blue: 135.0 / 255.0, alpha: 1)
var colors = OrcaColors(colorPalette: palette)
flavor.colors = colors
// Configure the language
flavor.localization.fixedLanguage = .fr
let customization = CdrCustomizationConfig(flavor: flavor)
Orca.cdr
.configure(with: cdrConfig)
.customize(with: customization)
.present { [weak self] result in
switch result {
case let .success(cdrResult):
/// Upload the CdrResult
break
case let .failure(error):
self?.handleCdrError(error)
break
}
}
}
Error handling
You need to handle the following error values:
Error | Description |
---|---|
Canceled | The client canceled the flow. |
DocumentExpired | The client's ID document has expired. |
DocumentTypeInvalid | The MRZ of the ID document in the document photo is different from the document type selected by the client. |
DocumentTypeNotSupported | The client's document type isn't supported. Check the list of supported countries and documents. |
IssuingCountryNotSupported | The issuing country of the client's ID document isn't supported. Check the list of supported countries and documents. |
NationalityNotSupported | The client's nationality isn't supported. Check the list of supported countries and documents. |
PersonNotAdult | The client is underage. |
Unexpected | An unexpected error occurred. Immediately report this issue to Fourthline along with the message code. |
Testing
Example code:
import FourthlineSDK
override func viewDidLoad() {
super.viewDidLoad()
Orca.cdr.testMe()
}
Analytics
The FourthlineCore
module collects and processes iOS SDK metrics.
You can set up an analytics observer for the SDK to forward Fourthline events to.
Events are only forwarded when you initialize FourthlineAnalytics
by calling FourthlineAnalytics.initialize(...)
with TrackingConsent
set to granted
.
- To set up the observer, call
FourthlineAnalytics.setObserver(...)
. - To remove the observer, call
FourthlineAnalytics.removeObserver()
.
import FourthlineCore
let observer = AnalyticsManager()
FourthlineAnalytics.setObserver(observer)
class AnalyticsManager: AnalyticsObserver {
func log(event: String, attributes: [String: Codable]?) {
// Log the Fourthline event
}
}
Data delegate
To receive notifications for each data group that the SDK uploads to Fourthline and a copy of the data itself, add a data delegate:
import FourthlineSDK
class MyClass {
func launchOrca() {
let configuration = WorkflowConfig(networkEnvironment: .mock)
let validationCode = "xxxxxxxx"
Orca.workflow(validationCode: validationCode)
.configure(with: configuration)
.addDelegate(self)
.present { [weak self] result in
switch result {
case let .failure(error):
self?.handleError(error)
case .success:
// Client has successfully finished the workflow.
break
}
}
}
}
// MARK: - WorkflowDataDelegate
extension MyClass: WorkflowDataDelegate {
func didUploadData(_ data: FourthlineSDK.WorkflowResults) {
switch data {
case let .idv(value: idvPart):
switch idvPart {
case let .document(document):
print("Did upload Document")
case let .documentVideo(video):
print("Did upload Document Video")
case let .selfie(selfie):
print("Did upload Selfie")
case let .selfieVideo(video):
print("Did upload Selfie Video")
case let .nfc(nfc):
print("Did upload Nfc")
case let .address(address):
print("Did upload Address")
case let .person(person):
print("Did upload Person")
case let .deviceMetadata(deviceMetadata):
print("Did upload Device Metadata")
}
default:
print("Handle Workflow data...")
}
}
}
Temporary files
The SDKs store some data collected during workflows (e.g. selfie and document videos) in the tmp/fourthline
folder in the client's device filesystem. This is because the videos must remain available until collected, packaged into a zipfile, and uploaded to our backend.
You must delete the temporary files when they are no longer needed, e.g. after the SDK has uploaded all data to Fourthline or immediately before the app is terminated in applicationWillTerminate
.
FileManager.default.deleteFourthlineFiles()
To integrate your solutions, see the Integration Guides section.
Updated 5 months ago