iOS SDK
The SDK provides a set of screens for capturing identity documents, face photos and profile data, and for performing the liveness check.
The SDK does not provide methods for obtaining verification results. You can either use the API to pull the results or rely on webhooks from the Dashboard.
Getting started
Requirements
- Xcode 13.0+
- Swift 5.5+
- iOS 15.1+
Obtaining an SDK key
In order to start using the Native SDK, you will need an SDK KEY
and API URL
.
Both can be provided by the Integration team.
Camera usage description
The SDK uses the camera for capturing photos during verification. The app is responsible for describing the reason for using the camera. You must add NSCameraUsageDescription
to the Info.plist of the app.
Using in Objective-C apps
If your app is written entirely in Objective-C, you should set Always Embed Swift Standard Libraries
to YES
in your app target's build settings.
Installation
Cocoapods
To install the iOS SDK, you need to add the following CDN link to your Podfile and then do a pod install.
pod 'GetID', podspec: 'https://cdn.getid.cloud/sdk/ios/<version>/GetID.podspec'
Swift Package Manager
Go to File > Swift Packages > Add Package Dependency
and add this repository: https://github.com/vvorld/getid-ios-sdk
The SDK version number you need to specify will be provided by Checkin.com.
Usage
Starting the flow
There are two ways to start the verification flow: using the SDK KEY
or using a JWT
. We recommend using JWT in the production environment. But during the development, you can use SDK KEY
, because it's a little bit more convenient.
At first, import GetID
to a .swift
file from which you plan to start the verification flow.
import GetID
Then call GetIDSDK.startVerificationFlow
method from the place in your code that responds to starting the verification flow. For example, it can be a handler of a button touch event.
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .sdkKey("SDK_KEY"),
flowName: "FlowName" // This can be set to the specific flow you want to use
)
To start the verification flow using a JWT
, your app should obtain the token from your backend.
Your backend should have the SDK KEY
to request the token from server.
Don't store SDK KEY
inside the app in the production environment!
To test starting the flow using a JWT
, you can obtain one. To obtain a JWT
make a POST request on your API URL
with SDK KEY
in the header:
$ curl -H "Content-Type: application/json" -H "x-sdk-key: SDK_KEY" -X POST API_URL/sdk/v2/token
Then pass the received token to GetIDSDK.startVerificationFlow
method:
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .jwt("JWT"),
flowName: "FlowName"
)
Profile data
If you have some information about the user before the verification flow started, you can pass it to the SDK as profileData
. This data is then cross-referenced with the data extracted from the uploaded documents.
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .jwt("JWT"),
flowName: "Standard",
profileData: .init(["first-name": "John", "gender": "male"])
)
External ID
You can also attach external IDs to the application, for instance, if you want to pass the internal ID
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .jwt("JWT"),
flowName: "Standard",
metadata: .init(externalId: "CEUD2R")
)
Locale
By default, the SDK gets the list of the device's preferred languages (it can be more than one on an iOS device). This means you don't have to set up the language of the verification flow's UI.
But if you want to override the default behavior by some reason, then pass locale
to GetIDSDK.startVerificationFlow
method.
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .jwt("JWT"),
flowName: "FlowName",
locale: "en"
)
Handling callbacks
If you want to handle the verification process completion then assign an object that conforms to theGetIDSDKDelegate
protocol to delegate
property of GetIDSDK
.
GetIDSDKDelegate method | Description |
---|---|
verificationFlowStart() | Tells the delegate that the verification flow has been successfully started. |
verificationFlowDidComplete(_:) | Tells the delegate that the user has completed the verification flow. The applicationId property of application parameter can be used for getting the verification status. |
verificationFlowDidCancel() | Tells the delegate that the user has canceled the verification flow. |
verificationFlowDidFail(_:) | Tells the delegate that the verification flow has been failed. |
Here is an example of handling the SDK callbacks:
import GetID
final class ViewController: UIViewController {
...
func startFlow() {
GetIDSDK.delegate = self
GetIDSDK.startVerificationFlow(
apiUrl: "API_URL",
auth: .jwt("JWT"),
flowName: "FlowName"
)
}
}
extension ViewController: GetIDSDKDelegate {
func verificationFlowDidStart() {
print("SDK has been started.")
}
func verificationFlowDidCancel() {
print("SDK has been cancelled.")
}
func verificationFlowDidFail(_ error: GetIDError) {
print("SDK has been completed with error: \(error). Description: \(error.localizedDescription)")
}
func verificationFlowDidComplete(_ application: GetIDApplication) {
print("SDK has been completed, applicationId: \(application.applicationId)")
}
}
Error Handling
If you experience build errors in the the Xcode project after adding the SDK, please disable User Script Sandboxing
.
There are two types of errors that can occur in the SDK:
GetIDError.InitializationError
GetIDError.FlowError
.
Both of the error types are enums. See the list of all possible cases in the tables below.
GetIDError.InitializationError | Description |
---|---|
invalidURL | Invalid API_URL . The correct one is the address of your Dashboard, for example https://company-name.getid.ee . |
invalidFlowName | Invalid flowName . |
invalidKey | Invalid SDK_KEY . |
invalidToken | Invalid JWT . Maybe, it has been expired. |
flowNotFound | There is no flow with the name you passed as flowName . See all the possible names in the Dashboard, at the Flows tab. |
unsupportedSchemaVersion(version:supportedVersions:) | It means that the SDK version is outdated. Note: schemaVersion != sdkVersion . |
applicationWithThisCustomerIdAlreadyExists | An application with this customerId already exists. |
GetIDError.FlowError | Description |
---|---|
tokenExpired | The token has been expired. |
unsupportedLivenessVersion(version:) | It means that the SDK version is outdated. |
applicationWithThisCustomerIdAlreadyExists | An application with this customerId already exists. |
failedToSendApplication(underlyingError:) | The SDK failed to send the captured data to the server (because of a network error, for example). |
Updated 2 days ago