General

Before integrating Passbase, you need to sign up on our developer dashboard. Integration of the Passbase iOS SDK follows a few simple steps:

1. Install the SDK through Cocoapods​

2. Initialize the SDK with your API key

3. Start a new verification process

4. Handling verifications

We suggest you follow our best practice how to integrate Passbase in your wider system in the overview section.

1. Install the SDK

Please use Cocoapods to install the SDK. If you don't have it installed already, please follow steps 1-2 from this guide.

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:

cd YourProject

pod init

This will create a Podfile inside your project. Open this file and add the following code to it.

First, add the following three lines at the top of your Podfile.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/passbase/zoomauthentication-cocoapods-specs.git'
source 'https://github.com/passbase/cocoapods-specs.git'

Include the iOS 11 requirement and use_frameworks!, like in the example below

Now, add the actual pod after the target of your app.

pod 'Passbase'

In order to install the SDK inside your project, go back to your terminal and run the following command inside your project folder:

pod install

This will install the Passbase SDK in your project and create a new .xcworkspace file inside your folder. Please use this file for future development, since all dependencies are installed here.

A full example of your Podfile will look something like this:

# 1. Add this here
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/passbase/zoomauthentication-cocoapods-specs.git'
source 'https://github.com/passbase/cocoapods-specs.git'
​
# 2. Add iOS requirements
platform :ios, '10.0'
​
target 'YourApp' do
   # 3. Add use_frameworks!
   use_frameworks!
   
   # 4. Add Passbase pod
   pod 'Passbase'
end
​

2. Initialize the SDK

Initialize the SDK in AppDelegate

Passbase uses API keys to allow access to the SDK and route it back to your dashboard. You need to register on our website and use your publishable API key from your developer dashboard's API settings. If you don't have a developer account yet, you can create one here: developer dashboard.​

Open the Workspace file in your directory. This 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 to import the Passbase SDK. Then, please add Passbase.initialize(publishableApiKey: "YOUR_PUBLISHABLE_API_KEY") within your didFinishLaunchingWithOptions function and replace "YOUR_PUBLISHABLE_API_KEY" with your own API key. You can find your publishable API key under API settings.

import Passbase
import UIKit
​
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
​
    var window: UIWindow?
​
​
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Passbase.initialize(publishableApiKey: "YOUR_PUBLISBALE_API_KEY")
        return true
    }
    
    ...
}

Adjust your App's Permissions

Please add the following permissions to your app's Info.plist, so that the Passbase iOS SDK can access user cameras 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, type privacy and add a camera usage description, and explain why you need to access the camera. Repeat the same step for photo library.

If you are more comfortable with code, right click on Info.plist and select Open As -> Source Code. Add the lines below somewhere inside the <dict> </dict>

<!-- permission strings to be include in info.plist -->
<key>NSCameraUsageDescription</key>
<string>Please give us access to your camera, to complete the verification.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Please give us access to your photo library to verify you.</string>

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.

Start Verification through the 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 automatically be rendered and trigger the verification flow.

Start Verification 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.

//Add to the top of the file
import Passbase
import UIKit
​
class ViewController: UIViewController {
​
  override func viewDidLoad() {
    super.viewDidLoad()
    
    // Add the button with dimensions
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
    
    // Or Add button with autolayout support
    let button = PassbaseButton(frame: .zero)
    button.translatesAutoresizingMaskIntoConstraints = false
    self.view.addSubview(button)
    let buttonConstraints = [
            button.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 50.0),
            button.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -50.0),
            button.topAnchor.constraint(lessThanOrEqualTo: self.view.topAnchor, constant: 60.0),
            button.heightAnchor.constraint(equalToConstant: 40),
    ]
    NSLayoutConstraint.activate(buttonConstraints)
  }
}

Prefilling email addresses

If you want to automatically prefill user email addresses, you can to skip the "Approve your Email" screen. This is available programmatically if you pass the prefillUserEmail parameter to the button.

import Passbase
import UIKit
​
class ViewController: UIViewController {
​
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Pass in the end users email to skip screen
        Passbase.prefillUserEmail = "testuser@yourproject.com"
​
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
        self.view.addSubview(button)
    }
}

Sending additionalAttributes

You can pass additional attributes along with the additionalAttributes object (e.g. additionalAttributes: ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]). This is useful if you want to pass an internal user ID, identifiers or other information to our dashboard. For instance, a user might have multiple email addresses they want to use over the lifetime on your platform. With this field, you'll be able to link all verifications back to that same user.

Code Example

import Passbase
import UIKit
​
class ViewController: UIViewController {
​
  override func viewDidLoad() {
    super.viewDidLoad()
    
    // Additionally attributes can be passed like this
    Passbase.additionalAttributes = ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]
    Passbase.prefillUserEmail = "testuser@yourproject.com"
​
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
  }
}

4. Handling verifications

In some cases, it's useful to know when a users completes or cancels a verification. We can use delegate methods to detect this. You need to complete 3 steps:

1. Add PassbaseDelegateat the class declaration of the view

2. Set the delegate to self in viewDidLoad

3. Implement the two delegate method

Code Example

import Passbase
import UIKit
​
// 1. Add PassbaseDelegate here 
class ViewController: UIViewController, PassbaseDelegate {
​
  override func viewDidLoad() {
    super.viewDidLoad()
    
    // 2. Set the delegate object to self
    Passbase.delegate = self
​
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
  }
​
  // 3. Implement the delegate methods
  func didCompletePassbaseVerification(authenticationKey: String) {
    print("didCompletePassbase with authenticationKey \(authenticationKey)")
  }
​
  func didCancelPassbaseVerification() {
    print("didCancelPassbase")
  }
}

We recommend the following process for handling identity verifications:

1. Obtain the authenticationKey of a successful identity verifications from the call back and save them to e.g. a user profile

2. Set up webhooks to be notified once the identity verification has been processed by our system. Also once your have approved or rejected the user in our dashboard

3. Now you can use your own backend to query the details about this identity verification with e.g. the authentication by key call to obtain the details

5. UI Customizations

We offer a variety of UI customizations for the button and other elements. For example, you can customize the color of the progress bar, button and different fonts. Please call these customizations on the Passbase.buttonUI object. Also ensure that you set the delegate object to self first.

Code Example

import Passbase
import UIKit
​
class ViewController: UIViewController {
​
  override func viewDidLoad() {
    super.viewDidLoad()
​
    Passbase.delegate = self
​
    // Optional - UI Customizations e.g.:
    // Button outside the flow to start
    Passbase.buttonUI.buttonBgColor: UIColor! = UIColor.white
​
    // Button inside the flow
    Passbase.buttonUI.loadingIndicatorColor: UIColor! = UIColor.passbaseBlue // Progress Bar & Loading Indicator
    Passbase.buttonUI.actionButtonBgColor: UIColor! = UIColor.black
    Passbase.buttonUI.actionButtonDeactivatedBgColor: UIColor! = UIColor.gray
    Passbase.buttonUI.actionButtonTextColor: UIColor! = UIColor.white
​
    // Disclaimer
    Passbase.buttonUI.disclaimerTextColor: UIColor! = UIColor.lightGray
​
    // Titles and subtitles of each steps
    Passbase.buttonUI.titleTextColor: UIColor! = UIColor.black
    Passbase.buttonUI.subtitleTextColor: UIColor! = UIColor.black
​
    let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
    self.view.addSubview(button)
  }
}

Example & Demo App

The code below is an implementation of a sample class with prefilled email, additional attributes and a UI customization.

You can find a complete sample App with both approaches (Storyboard & programmatic) on our Github page.

​Passbase iOS Demo App​

import Passbase
import UIKit
​
class ViewController: UIViewController, PassbaseDelegate {
​
    override func viewDidLoad() {
        super.viewDidLoad()
        Passbase.delegate = self
​
        // Optional - You can pass additional attributes here or prefill the email to skip that step.
        Passbase.additionalAttributes = ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]
        Passbase.prefillUserEmail = "testuser@yourproject.com"
​
        // Optional - UI Customizations e.g.:
        Passbase.buttonUI.actionButtonBgColor = .black
​
        let button = PassbaseButton(frame: CGRect(x: 40, y: 90, width: 300, height: 60))
        self.view.addSubview(button)
    }
    
    func didCompletePassbaseVerification(authenticationKey: String) {
        print("User completed Passbase Verification")
    }
​
    func didCancelPassbaseVerification() {
        print("User canceled Passbase Verification")
    }
}

​