App Drop-in Setup

Integrations guide

iOS SDK

This page sets out step-by-step instructions for setting up your App Drop-in via the iOS SDK.

Prerequisites & configuration

You will need your tenantId provided by Fourthline.

Operating system specifications:

  • Minimum iOS version: 12
  • MRZ detection in the document scanner requires minimum iOS 13.

GitHub credentials

Provide your implementation manager with the GitHub usernames and email addresses of your staff who need access to our repositories.

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.

Document data

Configurable

Discuss with your implementation manager what data to extract from ID document photos via optical character recognition (OCR):

Data typeDescription
MRZ dataDocument data is extracted from the MRZ only and is processed offline by the SDK.
MRZ & VIZ dataFor greater accuracy, document data is extracted from the MRZ and VIZ and processed by our AI agent in real time.

Supported devices

More information
For questions about supported devices, contact your implementation manager.


Flow

Follow these steps:

1. Add SDK to project

You can add the SDK to your project using Swift Package Manager, CocoaPods, or Carthage.

SDK versionCarthage Xcode Compatible
.xcframework
Cocoa Xcode Compatible
.xcframework
Minimum iOS version
2.28.0–latest14.3 and above14.3 and aboveiOS 12
2.23.0–2.27.014.314.3iOS 12
2.15.1–2.22.014.1–14.214.1–14.2iOS 12
2.11.3–2.15.013.3.1–13.413.3.1–13.4iOS 12
2.8.0–2.11.213.0–13.113.0–13.1iOS 12
2.6.0–2.7.012.511.0–12.5iOS 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)
Note
The YOUR_PROJECT_NAME.entitlements file is added to your project automatically.

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.

  1. 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-passport
  • A00000045645444C2D3031: Application ID for Dutch driving license

Example code:

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

2. Set up 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().

Example code:

import FourthlineCore

let observer = AnalyticsManager()
FourthlineAnalytics.setObserver(observer) 

class AnalyticsManager: AnalyticsObserver {
  func log(event: String, attributes: [String: Codable]?) {
    // Log the Fourthline event
  }
}

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

Example code:

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

4. Delete 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.

Example code:

FileManager.default.deleteFourthlineFiles()

5. Handle errors

You need to handle the following error values:

NameDescription
invalidValidationCodeThe validation code for the SDK session is invalid.
Action: Get a new validation code.
invalidWorkflowStatusThe status of the workflow is invalid, e.g. because the modules were completed successfully or with an error.
clientRejectedThe client isn't eligible for the Identity Verification workflow.
You can't retry.
canceledThe client canceled the workflow.
unexpectedAn unexpected error occurred.
Action: Contact your implementation manager immediately.
configurationNotSupportedThe workflow created with the validation code isn't supported.
Action: Consider updating to the latest SDK version.
moduleErrorThe 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.


6. Configure workflow modules

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.

Success
Success
You have configured and set up your App Drop-in!
To integrate your solutions, see the Integration Guides.

Top of page

Accordion in HTML5