Biometric/Pin

Cotter's Android 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.

There are major updates planned for this feature. Contact us in Slack so we can help you prepare for it.
Overview
Enabling PIN and Biometric using Cotter's Android SDK consists of:
1.Initializing Cotter
2.Calling functions to start Pin Enrollment and Biometric Enrollment
3.Verify Biometric or PIN before a transaction
4.Enabling and disabling Biometric or PIN in Settings
What you're building
PIN and Biometric using Cotter's Android SDK
Steps
1.​Import Cotter as a dependency​
2.​Set allowed Authentication Methods in the Dashboard
3.​Create a User​
4.​Initialize Cotter in your Main Activity
5.​Enroll Biometrics and PIN: PIN is recommended as a fallback method
6.​Verify Biometrics before a transaction
Step 1: Import Cotter as a dependency
Add JitPack repository your project level build.gradle at the end of repositories.
build.gradle
1
allprojects {
2
		repositories {
3
			...
4
			maven { url 'https://jitpack.io' }
5
		}
6
	}
Copied!
Add the Cotter's SDK as a dependency in your app level build.gradle .
1
android {
2
  ...
3
  compileOptions {
4
    sourceCompatibility JavaVersion.VERSION_1_8
5
    targetCompatibility JavaVersion.VERSION_1_8
6
  }
7
}
8
​
9
dependencies {
10
  ...
11
  implementation 'com.github.cotterapp:android-sdk:0.3.2'
12
}
Copied!
Check the latest version here https://github.com/cotterapp/android-sdk/releases.
Then sync your gradle files.
Step 2: Setting Authentication Methods
You need to set allowed methods for authenticating your users. To allow PIN and BIOMETRIC, go to https://dev.cotter.app/rules​
Set both Biometric and PIN to be allowed
Remember to set the correct Project in the dropdown list.
Step 3: Creating a User
1. Registering a User
Your server should do this request to Cotter's server during Registration.
Request
Response
1
curl -XPOST \
2
-H 'API_KEY_ID: <your key id>' \
3
-H 'API_SECRET_KEY: <your secret key>' \
4
-H "Content-Type: application/json" \
5
-d '{"client_user_id": "<Your User Identifier (string)>"}' \
6
'https://www.cotter.app/api/v0/user/create'
Copied!
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!
Check out Create a User API Reference for full Description
2. Get user data
To retrieve user's data:
Request
Response
1
curl -XGET \
2
-H 'API_KEY_ID: <your key id>' \
3
-H 'API_SECRET_KEY: <your secret key>' \
4
'https://www.cotter.app/api/v0/user/:your_user_id'
Copied!
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!
Check out Get User API Reference for full Description
Step 4: Initialize Cotter
You can now use the SDK to enroll and verify Biometric and PIN for the user you just created.
Initialize
In your MainActivity, initialize Cotter with API keys, Cotter's URL to use (prod/test), and your User ID.
Production Endpoint: https://www.cotter.app/api/v0
1
Cotter.init(
2
    this.getApplicationContext(),
3
    "https://www.cotter.app/api/v0",
4
    "<User ID>",
5
    "<API_KEY_ID>",
6
    "<API_SECRET_KEY>"
7
);
Copied!
Example:
MainActivity.java
1
public class MainActivity extends AppCompatActivity {
2
​
3
    @Override
4
    protected void onCreate(Bundle savedInstanceState) {
5
        ...
6
​
7
        Cotter.init(
8
            this.getApplicationContext(),
9
            "https://www.cotter.app/api/v0",
10
            "[email protected]",
11
            "588d6f67-0981-4718-899b-bcd512de1aca",
12
            "w4FK6Zz0XIhtGY3o5biI");
13
    }
14
    ...
Copied!
Step 5: Enroll Biometric and PIN
to enroll both Biometric and PIN, start the PinEnrollment flow in your Activity, pass in the Callback Screen, and the Event Tag. Event Tag is used for your own logging, for example, a pin enrollment event can be called "PIN_ENROLLMENT_ANDROID" to tag a pin enrollment event from an Android device.
1
Cotter.PinEnrollment.startFlow(view, CallBack.class, "EVENT TAG");
Copied!
Example:
1
// Inside your app, use a button onClick that calls
2
// openEnroll to start the flow
3
public void openEnrollment(View view) {
4
    Cotter.PinEnrollment.startFlow(view, Dashboard.class, "PIN_BIO_ENROLLMENT");
5
}
Copied!
How PinEnrollment looks like
After entering the PIN, the user will automatically be prompted to Enroll Biometrics if the device supports it. Entering a PIN is required as a fallback method.
PinEnrollment Flow
​
Step 6: Verify Biometrics on Transactions
The PinVerification 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 PinVerification flow is exactly the same as starting the PinEnrollment flow.
1
Cotter.setOnResetPin(new PinResetInterface() {
2
            @Override
3
            public void onResetPin(User user, Callback callback) {...}
4
})
5
Cotter.PinVerification.startFlow(view, CallBack.class, "EVENT TAG");
Copied!
In the verification page, there is a button called Forgot PIN . This is used to send a verification code to allow the user to reset their PIN.
setOnResetPin is used to set a callback function that will be called to reset the pin. You need to provide a function that follows the PinResetInterface. This function should call your server to initiate the PIN reset request.
When your onResetPin function is called, it should call your server, and your server needs to do the following:
1.Based on the currently logged-in user, find out the user's Email and name
2.Call Cotter's Reset PIN API to send the pin reset code
3.Receive the response from Cotter which contains the fields success, challenge_id, challenge
4.Call the callback.onSuccess with a JSONObject containing the following JSON object:
1
{
2
  "success": true,           // from the response from the Reset PIN API
3
  "challenge_id": 123,       // from the response from the Reset PIN API
4
  "challenge": "abcde12345", // from the response from the Reset PIN API
5
  "sending_method": "EMAIL",
6
  "sending_destination": "[email protected]"
7
}
Copied!
Example:
1
// In onCreate, set the onResetPin callback
2
protected void onCreate(Bundle savedInstanceState) {
3
     Cotter.setOnResetPin(new PinResetInterface() {
4
        @Override
5
        public void onResetPin(User user, Callback callback) {
6
            // 1. Call your server
7
            // 2. Get the response from your server
8
            // 3. Construct a JSONObject and pass it to callback.onSuccess
9
            JSONObject req = new JSONObject();
10
            try {
11
                req.put("success", response.getBoolean("success"));
12
                req.put("challenge_id", response.getInt("challenge_id"));
13
                req.put("challenge", response.getString("challenge"));
14
                req.put("sending_method", sendingMethod);
15
                req.put("sending_destination", sendingDestination);
16
            } catch (Exception e) {
17
                callback.onError(e.toString());
18
            }
19
    
20
            callback.onSuccess(req);
21
        }
22
    });
23
}
24
​
25
// Inside your app, use a button onClick that calls
26
// openPinVerification to start the flow
27
public void openPinVerification(View view) {
28
    Cotter.PinVerification.startFlow(view, Dashboard.class, "LOGIN");
29
}
Copied!
Reset PIN functionality is an update that is available starting from version 0.4.5
🎉 You're done!
​