- Solarisbank IdentHub SDK
iOS SDK for Solarisbank IdentHub.
It provides an easy way to integrate identification provided by Solarisbank into your iOS app.
IdentHub SDK requires minimum iOS version 12.
SDK Version | Cocoa Xcode Compatible .xcframework/.framework |
Minimum iOS support |
---|---|---|
0.3.0 | 11.0 - 12.4 | iOS 12 |
0.4.0 | 11.0 - 12.4 | iOS 12 |
0.5.0 | 11.0 - 12.4 | iOS 12 |
0.6.0 | 11.0 - 12.4 | iOS 12 |
0.7.0 | 11.0 - 12.4 | iOS 12 |
0.7.1 | 11.0 - 12.4 | iOS 12 |
1.0.0 | 11.0 - 12.4 | iOS 12 |
1.1.1 | 11.0 - 12.4 | iOS 12 |
1.1.2 | 13.0 - 13.1 | iOS 12 |
1.1.3 | 13.0 - 13.1 | iOS 12 |
1.2.0 | 13.0 - 13.1 | iOS 12 |
1.2.1 | 13.0 - 13.1 | iOS 12 |
1.2.2 | 13.0 - 13.1 | iOS 12 |
1.2.3 | 13.0 - 13.1 | iOS 12 |
1.2.4 | 13.0 - 13.1 | iOS 12 |
1.2.5 | 13.0 - 13.1 | iOS 12 |
1.2.6 | 13.0 - 13.1 | iOS 12 |
1.2.7 | 13.3.1 - 13.4 | iOS 12 |
1.2.8 | 13.3.1 - 13.4 | iOS 12 |
1.3.0 | 13.4 - 14.0 | iOS 12 |
1.4.0 | 13.4 - 14.0 | iOS 12 |
1.5.0 | 13.4 - 14.0 | iOS 12 |
1.5.1 | 13.4 - 14.0 | iOS 12 |
1.5.2 | 13.4 - 14.0 | iOS 12 |
1.5.3 | 13.4 - 14.3 | iOS 12 |
1.5.4 | 14.3 - 15.1 | iOS 12 |
1.5.5 | 14.3 - 15.1 | iOS 12 |
You can add the desired IdentHub SDK modules to your project by using CocoaPods dependency manager.
- git clone this repository.
- Run
make
command in the root directory and wait to get it finished. dist
folder has been created in project which contains all required .xcframework files. IdentHubSDK.xcframework and IdentHubSDKCore.xcframework are required frameworks. Others are required for specific identification methods only. For example, if you are integrating Bank Identification then include dist/bank/IdentHubSDKBank.xcframework in you project.
-
As a prerequisite, install CocoaPods on your machine (follow instructions at https://guides.cocoapods.org/using/getting-started.html).
-
Add Podfile to the root of your project (or extend existing one):
source 'https://github.com/Fourthline-com/FourthlineSDK-iOS-Specs.git' # to add Fourthline private pod
source 'https://github.com/CocoaPods/Specs.git' # to add other public pods
use_frameworks!
inhibit_all_warnings!
platform :ios, '12.0'
target 'YourTargetName' do
pod 'SolarisbankIdentHub', :git => "https://github.com/Solarisbank/identhub-ios.git", :tag => '1.5.5'
pod 'SolarisbankIdentHubCore', :git => "https://github.com/Solarisbank/identhub-ios.git", :tag => '1.5.5'
# Optional dependencies (See relevant section)
pod 'SolarisbankIdentHubBank', :git => "https://github.com/Solarisbank/identhub-ios.git", :tag => '1.5.5'
pod 'SolarisbankIdentHubQES', :git => "https://github.com/Solarisbank/identhub-ios.git", :tag => '1.5.5'
pod 'SolarisbankIdentHubFourthline', :git => "https://github.com/Solarisbank/identhub-ios.git", :tag => '1.5.5'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['BITCODE_GENERATION_MODE'] = 'bitcode'
end
end
end
-
Open Terminal and run
pod repo add fourthline-specs https://github.com/Fourthline-com/FourthlineSDK-iOS-Specs.git
command. You will be prompted to authenticate using the credentials you have been provided with in order to access the Fourthline SDK repository. (* if you experience any errors please see Troubleshooting) -
For first installation, run
pod install
inside your project root folder.- To update the Fourthline SDK, update the version value and run
pod update
inside your project root folder.
- To update the Fourthline SDK, update the version value and run
-
Open your project and build it.
The Fourthline SDK is not publicly available. Please get in contact with Solarisbank to request access to it.
The Solaris IdentHub SDK uses a modular approach that allows you to only include components that are necessary for the identification methods that you will actually use.
If you try to start an identification method for which one or more modules are missing, the IdentificationSession
will terminate with a failure modulesNotFound([<list of missing modules>])
.
The following modules are required dependencies for all identification methods and fundamental functionalities of the IdentHubSDK:
- SolarisbankIdentHub
- SolarisbankIdentHubCore
The following modules are required for specific identification methods only and may be skipped for other identification flows. Get in touch with your Integration Engineer to determine which modules should be included in your integration.
- SolarisbankIdentHubBank
- SolarisbankIdentHubQES
- SolarisbankIdentHubFourthline
First you need to create an identification session via the Solarisbank API. The session will contain a URL that can be passed to the IdentHub SDK to create a new session.
Add Privacy - Camera Usage Description
and Privacy - Location When In Use Usage Description
entries to Info.plist file, make sure that user granted access to Camera and Location services.
Swift
import SolarisbankIdentHub
// ... View Controller which is going to present IdentHub SDK
class ViewController: UIViewController {
@IBAction func startBankIdentSDK(_ sender: Any) {
let identHubSessionURL = … // from the API
let identHubSession = try IdentHubSession(rootViewController: self, sessionURL: identHubSessionURL)
identHubSession.start(self)
}
}
// MARK: IdentHubSDK Delegate
extension ViewController: IdentHubSDKManagerDelegate {
func didFinishWithSuccess(_ identification: String) {
DispatchQueue.main.async {
// - display success message on screen with identification -
}
}
func didFailureSession(_ failureReason: APIError) {
DispatchQueue.main.async {
// - display failure message
// - check the IdentificationSession's status in the backend wether app should retry
}
}
func didFinishOnConfirm(_ identification: String) {
DispatchQueue.main.async {
// - display a message stating the identification is in review -
}
}
}
Your app can be notified of the outcome of the IdentificationSession by implementing one of the following schemes:
- Provide a delegate that implements the IdentHubSDKManagerDelegate protocol
- Provide a callback handler and evaluate the provided
Result
object.
You can specify a delegate to take care of handling the IdentHubSession outcome:
/// Identification session results delegate
public protocol IdentHubSDKManagerDelegate: AnyObject {
/// Session finished with successful result and returns identification string
/// - Parameter identification: string value of the user identification
func didFinishWithSuccess(_ identification: String)
/// Identification session failed or interrupted with error
/// - Parameter failureReason: error object
func didFailureSession(_ failureReason: APIError)
/// Session finished with fourthline signing on confirm step and returns identification string
/// - Parameter identification: string value of the user identification
func didFinishOnConfirm(_ identification: String)
}
func didFinishWithSuccess(_ identification: String)
Method notifies when identification session finished with success and returns identification session identifier in parameter.
func didFailureSession(_ failureReason: APIError)
Method notifies when identification session finished or interrupted with error. Ask your backend (receives the webhooks), if app able to retry or not. App may retry as long as do not get a failed / rejected status on the session.
See also the description of the possible APIError values.
func didFinishOnConfirm(_ identification: String)
Method notifies when session finished with Fourthline signing on confirm step and returns identification string. Method is optional and used only for the Fourthline signing session method.
Alternatively to the implementation of a IdentHubSDKManagerDelegate, the IdentHubSession can be started with a completion handler:
/// Method starts identification process and calling the provided handler when completed.
/// - Parameter completion: closure to receive IdentificationSessionResult containing outcome of identification process.
public func start(_ completion: CompletionHandler?)
/// Completion handler type definition
public typealias CompletionHandler = (IdentificationSessionResult) -> Void
/// IdentHubSession result
public enum IdentificationSessionResult {
/// success - successful result with identification string in parameter
/// - identification: identification user session identifier
case success(identification: String)
/// failure - case used if identification process failed
/// - Parameter failureReason: error object
case failure(APIError)
/// onConfirm - success result of the Fourthline signing flow with identification value string in parameter
/// - identification: identification user session identifier
case onConfirm(identification: String)
}
/// Details about an IdentHubSession failure
public enum APIError: Error {
// ...
}
In case of a failure during the IdentHubSession, the partner's app will receive details about the failure through the provided APIError
.
APIError | Description |
---|---|
malformedResponseJson |
indicates that string received in the response couldn't been parsed. |
clientError |
indicates the error on the client's side. |
authorizationFailed |
indicates that authorization failed. |
unauthorizedAction |
action has not been authorized. |
resourceNotFound |
resource has not been found. |
expectationMismatch |
data mismatch's |
incorrectIdentificationStatus |
the identification status was not allowed to proceed with the action. |
unprocessableEntity |
data invalid or expired. |
internalServerError |
indicates the internal server error. |
requestError |
indicates build request error |
locationError |
indicates issue with fetching device location data |
locationAccessError |
The user did not give permission to access device location data |
ibanVerfificationFailed |
failed IBAN verification |
paymentFailed |
failed payment initiation |
identificationDataInvalid |
provided user data is not valid and should be creates one more time |
fraudData |
provided data defines as fraud |
unsupportedResponse |
SDK encountered a response that is not supported in this version |
identificationNotPossible |
SDK could not identify the user. Try your fallback identification method |
modulesNotFound |
one or more modules are missing for the chosen identification method. |
unknownError |
indicates that api client encountered an error not listed above. |
IdentHubSession class has static method version()
.
Method returns current version of SDK in format (version + build number): v1.0(1)
You can open the example app in XCode to try it out.
You can find the example code in Sample
directory.
While trying to call pod repo add fourthline-specs https://github.com/Fourthline-com/FourthlineSDK-iOS-Specs.git
if you experience the following error:
remote: Invalid username or password
fatal: Authentication failed for 'https://github.com/Fourthline-com/FourthlineSDK-iOS-Specs.git/'
Fourthline requires to use GitHub 2 factor authentication, please use a PAT instead of a password when trying to authenticate. How to create a PAT can be found at -> https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
If you get "Redefinition of module 'libtesseract'" and "Redefinition of module 'libleptonica'" errors at module.private.modulemap file while building your app, comment out next lines of code:
module libtesseract {
export *
}
module libleptonica {
export *
}
If you get "Missing modules 'libtesseract', 'libleptonica'" while uploading app to AppStore, make sure that module.private.modulemap file is not missing at SwiftyTeseeract.framework/Modules/ folder. You can find content of file in previous section.
If you get "bitcode bundle could not be generated because '/Path/To/Framework/FrameworkName.framework/FrameworkName' was built without full bitcode." error, you need to rebuild that framework with bitcode enabled.
For this go to Build settings of framework target in framework project and make sure:
- Enable bitcode is set to Yes.
- Other C Flags contains -fembed-bitcode value.
- User defined settings contain BITCODE_GENERATION_MODE key with bitcode value.
Rebuild and reimport problematic framework.
If you get error message similar to next one: "Class XXX is implemented in both YYY and /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/macosx/libswiftCore.dylib. One of the two will be used. Which one is undefined.", you need to add empty swift file to your pure ObjC application, together with bridging file (will be created automatically by Xcode).
If you get error "/Path/To/Your/Project/ProjectName.xcodeproj Building for iOS Simulator, but the linked and embedded framework 'FrameworkName.framework' was built for iOS.", you need to rebuild that framework with arm64 architecture excluded for iOS Simulator.
For this go to Build settings of framework target in framework project and make sure that Excluded Architectures property contains arm64 value for Any iOS Simulator SDK option for desired build target (Debug, Release)
Rebuild and reimport problematic framework.
Alternatively, you can add the following script at the end of the Podfile:
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
end
end
end
If you get error Building for iOS, but the linked and embedded framework 'FourthlineCore.framework' was built for iOS + iOS Simulator.
This was introduced in Xcode 12.3 and is a reminded for pushing teams to use .xcframeworks instead of .frameworks for dependencies.
Please go to Build Settings
and set Validate Workspace
to NO (if is already set, change it to YES and change it back to NO, it seems to be an Xcode visual bug for now, by default is set to YES(Error))
Validate Workspace |
Description |
---|---|
YES | validate workspace and show warnings |
NO | skip validation of workspace |
YES(Error) | validate workspace and show errors |