iOS - Passbase Docs

General
Please ensure that you are using the latest XCode version, since the SDK is written in Swift 5.5. As of this writing, this is Xcode 13.0. Please also install Cocoapods, if you haven't already.
Before integrating Passbase, we suggest you read first our best practice on how to integrate Passbase in your system in the overview section and complete the initial setup steps.
You can either follow the integration guide or watch the integration tutorial that shows the same steps. Please be aware that some property or function names might have slightly changed with newer versions. Make sure to compare your implementation with the latest code snippets here in the documentation.
1. Install the SDK
Swift Package Manager
CocoaPods
To install the SDK, follow these steps:
1.In Xcode, select File > Swift Packages > Add Package Dependency and enter https://github.com/passbase/passbase-sp.git as the repository URL.
2.Select a minimum version of 2.9.2
3.Add the Passbase product to the target of your app.
If you haven’t already, install the latest version of CocoaPods.
If you don't have a Podfile in your project yet, please create one. To do this, open a terminal window. Then, navigate to your iOS project's folder and run:pod init
This will create a Podfile inside your project. Open this file and add the following code to the top of it: 
1
source 'https://github.com/CocoaPods/Specs.git'
2
source 'https://github.com/passbase/cocoapods-specs.git'
3
source 'https://github.com/passbase/microblink-cocoapods-specs.git'
Copied!
Next, add the actual pod after the target of your app. Include also the iOS 11 requirement and use_frameworks!, like in the example below.
1
# 1. Add this here
2
source 'https://github.com/CocoaPods/Specs.git'
3
source 'https://github.com/passbase/cocoapods-specs.git'
4
source 'https://github.com/passbase/microblink-cocoapods-specs.git'
5
​
6
# 2. Add iOS requirements
7
platform :ios, '11.0'
8
​
9
target 'YourApp' do
10
   # 3. Add use_frameworks!
11
   use_frameworks!
12
   
13
   # 4. Add Passbase pod
14
   pod 'Passbase'
15
end
16
​
Copied!
Finally, run pod install to install the Passbase SDK in your project. This will create a new .xcworkspace file inside your project's folder. Please use this file for future development, since all dependencies are installed here.
 If you need to update to the latest pod, use the command pod update inside your directory to pull the latest podspec version and get the latest version of the SDK.
You have successfully installed the Passbase SDK in your iOS application!  🎉
2. Initialize the SDK
Initialize the SDK in AppDelegate
Please use the publishable API key for all integrations. The secret key should never be exposed or used in a web integration or mobile app since it can access sensitive user data if leaked!
Open the Workspace file in your directory. This file was created through the previous step with CocoaPods. It will be called something like YourProject.xcworkspace.
Now, open your AppDelegate.swift file and add import Passbase to the top. Then add the initialize method with your publishable API key from your API settings. Your code should look now like below:
1
import Passbase
2
import UIKit
3
​
4
@UIApplicationMain
5
class AppDelegate: UIResponder, UIApplicationDelegate {
6
​
7
    var window: UIWindow?
8
​
9
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
10
        PassbaseSDK.initialize(publishableApiKey: "YOUR_PUBLISBALE_API_KEY")
11
        return true
12
    }
13
​
14
}
Copied!
Adjust Your App's Permissions
If you made it until here, you've successfully installed the Passbase SDK for iOS. Now let's adjust your last settings and start your first verification.
Please add the following permissions to your app's Info.plist, so that the Passbase iOS SDK can access a user's camera to run a verification. You can do this in the property list view or by code.
Right-click somewhere outside the table and select Add Row. Now add the entries like below.
Or if you prefer to do this step with code, right-click on Info.plist and select Open As -> Source Code. Add the lines below somewhere inside the <dict>   </dict> 
1
<!-- permission strings to be include in info.plist -->
2
<key>NSCameraUsageDescription</key>
3
<string>Please give us access to your camera, to complete the verification.</string>
4
<key>NSPhotoLibraryUsageDescription</key>
5
<string>Please give us access to your photo library to verify you.</string>
Copied!
You have successfully finished setting up the Passbase iOS SDK! 🎉
3. Start a Verification
To start a new verification, you can either trigger it through the storyboard or by code. This section will walk you through both.
Keep in mind that in order to successfully finish a verification, you need to pass our liveness detection. Hence, if you develop on a Simulator (e.g. iPhone Simulator via Xcode), you will only see the UI Demo Mode of our SDK. Therefore please use a real device (e.g. an attached iPhone) to fully test and develop with our SDK.
Add Button via Storyboard
Two simple steps to get the button running:
1.Drag a new button on your storyboard and give it your desired constraints.
2.Subclass the button as PassbaseButton. Ensure that the module also says Passbase below the class.
That's it! The button should now be rendered and trigger the verification flow.
Add Button Programmatically
To start the verification flow programmatically, create a new button of type PassbaseButton. You can give it parameters, like width, height, x & y through the CGRect and add constraint to position the button.
1
//Add to the top of the file
2
import Passbase
3
import UIKit
4
​
5
class ViewController: UIViewController {
6
​
7
  override func viewDidLoad() {
8
    super.viewDidLoad()
9
    
10
    // Add the button with dimensions
11
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
12
    self.view.addSubview(button)
13
    
14
    // Or Add button with autolayout support
15
    let button = PassbaseButton(frame: .zero)
16
    button.translatesAutoresizingMaskIntoConstraints = false
17
    self.view.addSubview(button)
18
    let buttonConstraints = [
19
            button.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 50.0),
20
            button.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -50.0),
21
            button.topAnchor.constraint(lessThanOrEqualTo: self.view.topAnchor, constant: 60.0),
22
            button.heightAnchor.constraint(equalToConstant: 40),
23
    ]
24
    NSLayoutConstraint.activate(buttonConstraints)
25
  }
26
}
Copied!
Prefilling Email Addresses
If you want to automatically prefill user's email address to skip the "Approve your Email" screen. This is available programmatically if you pass the prefillUserEmail parameter to the button like below. 
1
import Passbase
2
import UIKit
3
​
4
class ViewController: UIViewController {
5
​
6
    override func viewDidLoad() {
7
        super.viewDidLoad()
8
        
9
        // Pass in the end users email to skip screen
10
        PassbaseSDK.prefillUserEmail = "[email protected]"
11
​
12
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
13
        self.view.addSubview(button)
14
    }
15
}
Copied!
Prefilling Country
You can automatically prefill user's country in the drop-down list. This is available programmatically if you pass the prefillCountry parameter to the button like below. An ISO-3166 compliant country code, case insensitive. This will not enable skipping the country selection step. 
1
import Passbase
2
import UIKit
3
​
4
class ViewController: UIViewController {
5
​
6
    override func viewDidLoad() {
7
        super.viewDidLoad()
8
        
9
        // Pass in the end users email to skip screen
10
        PassbaseSDK.prefillCountry = "de"
11
​
12
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
13
        self.view.addSubview(button)
14
    }
15
}
Copied!
Prefilling metaData
If you are tracking end users in your backend through an internal UUID, transaction number, stripe ID, etc., you can use the metaData object to securely pass encrypted end user information to identify completed verifications. The metadata object requires an encrypted JSON string via the private key encoded in base64. 
​
Value
metaData
Encrypted JSON string via the private key encoded in base64
1
import Passbase
2
import UIKit
3
​
4
class ViewController: UIViewController {
5
​
6
    override func viewDidLoad() {
7
        super.viewDidLoad()
8
        
9
        // Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
10
        PassbaseSDK.metaData = "AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD"
11
​
12
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
13
        self.view.addSubview(button)
14
    }
15
}
Copied!
Add Encryption Key to your Project
Encryption should be completed on the server-side. Once you have completed the encryption, please enter the encryption keys for each individual project within the developer dashboard. The metaData object is then returned on the Passbase API.
​Click here to view metaData encryption documentation.
Retrieve MetaData from Passbase API
After a user completes a verification and you receive the VERIFICATION_REVIEWED webhook event, it is time to call the Passbase Get Identity endpoint.  Using this API endpoint, you will see the new metaData object returned.
If the public encryption key is not added to the developer dashboard, you will not see the metaData information returned on the API.
1
{
2
   id: "1234-1234-1234-1234",
3
   resources: [...],
4
   metadata: { internal_customer_id: "XYZ" }
5
}
Copied!
You have successfully started your first verification. 🎉
4. Handling Verifications
In some cases it's useful to know if a user has completed the verification flow or canceled it. For this, you can implement the following delegate/callback methods:
Method
Description
onStart
This callback method is triggered once a user starts the verification flow. 
onSubmitted
Method that is being called once verification data is submitted to Passbase.
You receive an object called identityAccessKey which can be used to access the identity. Please see our section about Webhooks and API for more information.
onFinish
Method that is being called once a user clicks the "Finish" button. You receive an object called identityAccessKey which can be used to access the identity. Please see our section about Webhooks and API for more information.
onError
This callback method is triggered if a user canceled the verification flow or the verification flow finished with an error. You can use this to find out if people dropped out of your verification flow.
Error codes:
CANCELLED_BY_USER 
BIOMETRIC_AUTHENTICATION_FAILED
Code Example
1
import Passbase
2
import UIKit
3
​
4
// 1. Add PassbaseDelegate here 
5
class ViewController: UIViewController, PassbaseDelegate {
6
​
7
  override func viewDidLoad() {
8
    super.viewDidLoad()
9
    
10
    // 2. Set the delegate object to self
11
    PassbaseSDK.delegate = self
12
​
13
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
14
    self.view.addSubview(button)
15
  }
16
​
17
  // 3. Implement the delegate methods
18
  func onFinish(identityAccessKey: String) {
19
    print("onFinish with identityAccessKey \(identityAccessKey)")
20
  }
21
  
22
  func onSubmitted(identityAccessKey: String) {
23
    print("onSubmitted with identityAccessKey \(identityAccessKey)")
24
  }
25
​
26
  func onError(errorCode: String) {
27
    print("onError with code \(errorCode)")
28
  }
29
  
30
  func onStart() {
31
    print("onStart")
32
  }
33
}
Copied!
We recommend the following process for handling identity verifications:
1.Obtain the identityAccessKey of a successfully completed identity verification from the callback method and save it to your DB to the user's profile
2.Set up webhooks to be notified once the identity verification has been processed by our system. Also once you have approved or declined the user in your dashboard
3.Now you can use your own backend to query the details about this identity verification with e.g. the Get Identity call to obtain the details 
Identity Access Key as Reference
In order for your application to interoperate with Passbase, you should reference to your users once the Verification is completed.
For that, you will need to keep track of the identityAccessKey returned by the onFinish or onSubmitted callbacks and associate it in your backend with your end users' id. We recommend to save this key after the onSubmitted method from your user's completed verification, or listen for the incoming webhooks to make a call to the Passbase API linking back the email address of the user.
5. UI Customizations
Appearance
Our SDK currently supports a set of customization options which will influence the appearance. To customize the verification flow, please navigate to your developer dashboard's customization section. Here you can choose amongst a variety of colors, fonts, accepted countries & much more.
Customization Section
We also offer a dark mode, which will be automatically started if a user has activated this in his system settings.
Dark Mode 
Language 
We support a variety of different languages for the verification flow. As of this writing more than 10 including (English, Spanish, German & many more). If one is missing and you want us to add support for it, please reach out to our customer support.
The SDK automatically detects the language of the user's phone settings. If we support the language, the verification flow will be set to it. Otherwise, the default is English.
Example & Demo App
The code below is a sample implementation of a class with prefilled email and button added via code. You can find a complete sample App with both approaches (Storyboard & programmatic) on our Github page.
Link: Passbase iOS Demo App​
1
import Passbase
2
import UIKit
3
​
4
class ViewController: UIViewController, PassbaseDelegate {
5
​
6
    override func viewDidLoad() {
7
        super.viewDidLoad()
8
        PassbaseSDK.delegate = self
9
​
10
        // Optional - You can prefill the email to skip that step.
11
        Passbase.prefillUserEmail = "[email protected]"
12
​
13
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
14
        self.view.addSubview(button)
15
    }
16
    
17
    func onFinish(identityAccessKey: String) {
18
      print("onFinish with identityAccessKey \(identityAccessKey)")
19
    }
20
    
21
    func onSubmitted(identityAccessKey: String) {
22
      print("onSubmitted with identityAccessKey \(identityAccessKey)")
23
    }
24
  
25
    func onError(errorCode: String) {
26
      print("onError with code \(errorCode)")
27
    }
28
    
29
    func onStart() {
30
      print("onStart")
31
    }
32
}
Copied!