Biometric/Pin

Cotter's iOS SDK helps you easily add a Biometric prompt or PIN fallback to your app. This is useful for protecting transactions or sensitive information like medical records.

Overview
Enabling PIN and Biometric using Cotter's Android SDK consists of: 
1. Initializing Cotter
2.Calling functions to start PIN and Biometric Enrollment
3.Verify Biometric or PIN before an action
4.Enabling and disabling Biometric or PIN in Settings
What you're building
Biometric and PIN using Cotter's SDK
Steps
1.​Installation​
2.​Set allowed Authentication Methods in the Developer Dashboard​
3.​Initialize Cotter as a dependency​
4.​Create a User​
5.​Enroll PIN or Biometric​
6.​Verify PIN and/or Biometrics on an action​
Step 1. Installation
We use Cocoapods as our SDK host. If you're using Cocoapods, add this to your Podfile
1
pod 'Cotter'
Copied!
Otherwise please open an issue at our Github Issues page.
Then simply run pod install
Step 2. Set allowed Authentication Methods in the Developer Dashboard
You need to set allowed methods for authentication your users. To allow PIN and BIOMETRIC, go to https://dev.cotter.app/rules​
Set both Biometric and PIN to be allowed
Remember to select the correct project in the dropdown list
Step 3. Initializing Cotter
You will have to do import Cotter on the file that will use Cotter. Then do initialization as follows
1
import Cotter...let cotter = Cotter(
2
 apiSecretKey: <your-api-secret-key>,
3
 apiKeyID: <your-api-key-id>,
4
 cotterURL: "https://www.cotter.app/api/v0",
5
 userID: <your-user-id>, // user’s id that will be created later
6
 configuration: <your-cotter-config>
7
)
Copied!
example:
1
import Cotter...let cotter = Cotter(
2
 apiSecretKey: "<API_SECRET_KEY>",
3
 apiKeyID: "<API_KEY_ID>",
4
 cotterURL: "https://www.cotter.app/api/v0",
5
 userID: "[email protected]",
6
 configuration: [:]
7
 );
Copied!
Step 4. Creating a User
1. Registering a new User
1
/* https://www.cotter.app/api/v0/user/create */
2
CotterAPIService.shared.registerUser(
3
  userID: <your-user-id>,
4
  cb: { response in
5
    // handle Result (Swift 5 enum) callback here
6
  }
7
)
Copied!
Response:
1
{
2
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
3
  "created_at": "2020-01-21T12:40:21.200727668Z",
4
  "update_at": "2020-01-21T12:40:21.200727668Z",
5
  "deleted_at": null,
6
  "issuer": "<your key ID>",
7
  "client_user_id": "<Your User Identifier (string)>",
8
  "enrolled": [],
9
  "default_method": null
10
}
Copied!
Example:
1
// registerUserCb is a simple callback that handles the cases for 
2
// the API Call
3
func registerUserCb(_ response: CotterResult<CotterUser>){
4
    switch response{
5
    case .success(let user):
6
        print("successfully registered the \(user)")
7
​
8
    case .failure(let err):
9
        // you can put exhaustive error handling here
10
        switch err{
11
        case CotterAPIError.decoding:
12
            print("this is decoding error on registering user")
13
            break
14
        case CotterAPIError.network:
15
            print("this is network error on registering user")
16
            break
17
        case CotterAPIError.status:
18
            print("this is not successful error")
19
            break
20
        default:
21
            print("error registering user: \(err)")
22
        }
23
    }
24
}
25
​
26
// call the API using our client
27
CotterAPIService.shared.registerUser(
28
    userID: "[email protected]",
29
    cb: registerUserCb
30
)
Copied!
2. Get a User
1
/* https://www.cotter.app/api/v0/user/:your_user_id */
2
CotterAPIService.shared.getUser(
3
  userID: <your-user-id>,
4
  cb: { response in
5
    // handle Result (Swift 5 enum) callback here
6
  }
7
)
Copied!
Response:
1
{
2
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
3
  "created_at": "2020-01-21T12:40:21.200727668Z",
4
  "update_at": "2020-01-21T12:40:21.200727668Z",
5
  "deleted_at": null,
6
  "issuer": "<your key ID>",
7
  "client_user_id": "<Your User Identifier (string)>",
8
  "enrolled": ["PIN", "BIOMETRIC"],
9
  "default_method": "BIOMETRIC"
10
}
Copied!
Example:
1
func enrollCb(response: CotterResult<CotterUser>) {
2
    switch response {
3
    case .success(let resp):
4
        self.yourLabel.text = resp.enrolled.joined(separator: ", ")
5
    case .failure(let err):
6
        // we can handle multiple error results here
7
        switch err {
8
        case CotterAPIError.status(code: 500):
9
            print("internal server error")
10
        case CotterAPIError.status(code: 404):
11
            print("user not found")
12
        default:
13
            print(err.localizedDescription)
14
        }
15
    }
16
}
17
​
18
CotterAPIService.shared.getUser(userID:self.userID, cb:enrollCb)
Copied!
Step 5. Enroll PIN or Biometric
For starting authentication flow, you need to have the following:
The UIViewController you want to attach Cotter to
The UIViewController MUST have a NavigationController set (i.e. self.navigationController cannot be nil)
1
// initialization
2
let cotter = Cotter(...)cotter.PinEnrollment.startEnrollment(
3
 vc: <your-vc>,
4
 animated: true,
5
 cb: <your-callback>
6
);
Copied!
example:
1
class SomeUIVC: UIViewController {
2
  var cotter: Cotter?
3
  override func viewDidLoad() {
4
      super.viewDidLoad()
5
      // cotter initialization here
6
      self.cotter = Cotter(
7
          apiSecretKey: "588d6f67-0981-4718-899b-bcd512de1aca",
8
          apiKeyID: "w4FK6Zz0XIhtGY3o5biI",
9
          userID: "[email protected]",
10
          cotterURL: "https://www.cotter.app/api/v0",
11
          configuration: [:]
12
        );
13
      cotter.startEnrollment(
14
        vc: self,
15
        animated: true,
16
        cb: { (token: String, err: Error?) in
17
            if err != nil {
18
                // handle error
19
                return
20
            }
21
            // handle success
22
        }
23
      )
24
  }
25
}
Copied!
Step 6. Verify PIN and/or Biometrics on an action
The verification flow will automatically prompt for Biometric Verification if the user's device has an enrolled biometric. Otherwise, it will fallback to entering PIN. Starting the verification flow is exactly the same as starting the Enrollment Flow on step 5.
1
// initialization
2
let cotter = Cotter(...)
3
​
4
cotter.PinEnrollment.startTransaction(
5
  vc: <your-vc>,
6
  animated: true,
7
  cb: <your-callback>,
8
  hideClose: false, // hideClose param gives you the choice to show/hide the close button
9
  configuration: [:]
10
);
Copied!
Example:
1
class SomeUIVC: UIViewController {
2
  var cotter: Cotter?
3
​
4
  override func viewDidLoad() {
5
      super.viewDidLoad()
6
​
7
      // cotter initialization here
8
      self.cotter = Cotter(
9
          apiSecretKey: "<your API_SECRET_KEY>",
10
          apiKeyID: "<your API_KEY_ID>",
11
          userID: "[email protected]",
12
          cotterURL: "https://www.cotter.app/api/v0"
13
        );
14
​
15
      cotter.startTransaction(
16
        vc: self,
17
        animated: true,
18
        cb: { (token: String, err: Error?) in 
19
            if err != nil {
20
                // handle error
21
                return
22
            }
23
            // handle success
24
        },
25
        hideClose: false
26
      )
27
  }
28
}
Copied!
🎉 You're done!
Additional Notes
The Callbacks
There are 2 types of callback:
1. HTTP Callbacks
HTTP Callbacks are the ones that you pass in to the start flow functions (startEnrollment, startTransaction, startUpdateProfile).
The callback form is as such:
1
// FinalCallbackAuth is the general callback function declaration
2
public typealias FinalAuthCallback = (_ token: String, _ error: Error?) -> Void
Copied!
It takes in a token String and an optional Error object. Currently token String is not used in PIN or Biometric authentication. We're working on making the token useable.
Error types
For the FinalAuthCallback function, there are 3 types of CotterError that exist in the SDK. These include:
1. CotterError.biometricEnrollment
This error is produced when you fail to enroll your biometrics during the Enrollment flow in startEnrollment.
2. CotterError.biometricVerification
 This error is produced when you fail to verify your biometrics during the Transaction flow in startTransaction.
3. CotterError.keychainError
This error is produced in all flows when the user's device is unable to attain its corresponding public/private keys.
However, you will almost always only encounter CotterError.biometricEnrollment and CotterError.biometricVerification errors in the resulting FinalAuthCallback function.
2. Authentication Callbacks
Authentication Callbacks are the ones that is passed in through the CotterAPIService. It uses the latest Result enum in Swift 5. The Authentication callback works similarly as the HTTP Callback, it can handle success and error cases as shown on the previous example.
The callback form is as such:
1
public typealias ResultCallback<Value> = (Result<Value, Error>) -> Void
Copied!
What this definition says is that it takes a Result of a type Value, which Value can be any of the pre defined Cotter classes (such as CotterUser, CotterEvent, etc), and returns nothing.
Error types
When using the CotterAPIService class to call Cotter's API endpoints, there are 5 types of Cotter errors that you might encounter:
1. CotterAPIError.encoding
An 'encoding' error refers to an error encoding the HTTP Request.
2. CotterAPIError.decoding
A 'decoding' error refers to an error decoding the HTTP Response.
3. CotterAPIError.status(code: Int)
A 'status' error refers to the response having an invalid HTTP Status Code - e.g. Status 400 (Bad Request Error)
4. CotterAPIError.server(message: String)
A 'server' error means that our API server has responded to the request with an error message.
5. CotterAPIError.network
A 'network' error means that network conditions are poor, which can be due to bad internet connection.
​