# Biometric/Pin

{% hint style="warning" %}
There are major updates planned for this feature. [Contact us in Slack](https://join.slack.com/t/askcotter/shared_invite/zt-dxzf311g-5Mp3~odZNB2DwYaxIJ1dJA) so we can help you prepare for it.
{% endhint %}

### 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](https://107069962-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0QGDMRD8y_Kd-BpOvT%2F-M0RamYrpZW_1DrQkWig%2F-M0Ray-M6mEFhHMiUl5r%2Fimage.png?alt=media\&token=7326625f-fd49-4314-b5ce-63c33d7f14ff)

## Steps

1. [Import Cotter as a dependency](#step-1-import-cotter-as-a-dependency)
2. [Set allowed Authentication Methods](#step-2-setting-authentication-methods) in the Dashboard
3. [Create a User](#step-3-creating-a-user)
4. [Initialize Cotter](#step-4-initialize-cotter) in your Main Activity
5. [Enroll Biometrics and PIN](#step-5-enroll-biometric-and-pin): PIN is recommended as a fallback method
6. [Verify Biometrics](#step-6-verify-biometrics-on-transactions) before a transaction

### Step 1: Import Cotter as a dependency

Add JitPack repository your project level `build.gradle` at the end of repositories.

{% code title="build.gradle" %}

```java
allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}
```

{% endcode %}

Add the Cotter's SDK as a dependency in your app level `build.gradle` .

```java
android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  ...
  implementation 'com.github.cotterapp:android-sdk:0.3.2'
}
```

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](https://107069962-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0QGDMRD8y_Kd-BpOvT%2F-M0RcwC39Aa6gMrCO5Lc%2F-M0Rd71oJbeus4CzKUIm%2Fimage.png?alt=media\&token=3a62b535-9176-4947-b35a-56d5f8e0574c)

{% hint style="info" %}
Remember to set the correct Project in the dropdown list.
{% endhint %}

### Step 3: Creating a User

#### 1. Registering a User <a href="#id-1-registering-a-user" id="id-1-registering-a-user"></a>

Your server should do this request to Cotter's server **during Registration**.

{% tabs %}
{% tab title="Request" %}

```http
curl -XPOST \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
-H "Content-Type: application/json" \
-d '{"client_user_id": "<Your User Identifier (string)>"}' \
'https://www.cotter.app/api/v0/user/create'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": [],
  "default_method": null
}
```

{% endtab %}
{% endtabs %}

Check out [Create a User API Reference](https://docs.cotter.app/api-reference/user-api#create-a-user) for full Description

#### 2. Get user data

To retrieve user's data:

{% tabs %}
{% tab title="Request" %}

```
curl -XGET \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
'https://www.cotter.app/api/v0/user/:your_user_id'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": ["PIN", "BIOMETRIC"],
  "default_method": "BIOMETRIC"
}
```

{% endtab %}
{% endtabs %}

Check out [Get User API Reference](https://docs.cotter.app/api-reference/user-api#get-user) 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 <a href="#initialize" id="initialize"></a>

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`

```java
Cotter.init(
    this.getApplicationContext(),
    "https://www.cotter.app/api/v0",
    "<User ID>",
    "<API_KEY_ID>",
    "<API_SECRET_KEY>"
);
```

Example:

{% code title="MainActivity.java" %}

```java
public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...

        Cotter.init(
            this.getApplicationContext(),
            "https://www.cotter.app/api/v0",
            "hello@example.com",
            "588d6f67-0981-4718-899b-bcd512de1aca",
            "w4FK6Zz0XIhtGY3o5biI");
    }
    ...
```

{% endcode %}

### 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.

```java
Cotter.PinEnrollment.startFlow(view, CallBack.class, "EVENT TAG");
```

Example:

```java
// Inside your app, use a button onClick that calls
// openEnroll to start the flow
public void openEnrollment(View view) {
    Cotter.PinEnrollment.startFlow(view, Dashboard.class, "PIN_BIO_ENROLLMENT");
}
```

#### 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](https://107069962-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0QGDMRD8y_Kd-BpOvT%2F-M0Rhq8aBaauZN-bXKc6%2F-M0Ri4hUvJsW7AYs-tt-%2Fimage.png?alt=media\&token=33717251-bdfa-4de2-96dd-388c20424ad1)

### **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.

```java
Cotter.setOnResetPin(new PinResetInterface() {
            @Override
            public void onResetPin(User user, Callback callback) {...}
})
Cotter.PinVerification.startFlow(view, CallBack.class, "EVENT TAG");
```

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](https://docs.cotter.app/api-reference/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:

```javascript
{
  "success": true,           // from the response from the Reset PIN API
  "challenge_id": 123,       // from the response from the Reset PIN API
  "challenge": "abcde12345", // from the response from the Reset PIN API
  "sending_method": "EMAIL",
  "sending_destination": "user@email.com"
}
```

Example:

```java
// In onCreate, set the onResetPin callback
protected void onCreate(Bundle savedInstanceState) {
     Cotter.setOnResetPin(new PinResetInterface() {
        @Override
        public void onResetPin(User user, Callback callback) {
            // 1. Call your server
            // 2. Get the response from your server
            // 3. Construct a JSONObject and pass it to callback.onSuccess
            JSONObject req = new JSONObject();
            try {
                req.put("success", response.getBoolean("success"));
                req.put("challenge_id", response.getInt("challenge_id"));
                req.put("challenge", response.getString("challenge"));
                req.put("sending_method", sendingMethod);
                req.put("sending_destination", sendingDestination);
            } catch (Exception e) {
                callback.onError(e.toString());
            }
    
            callback.onSuccess(req);
        }
    });
}

// Inside your app, use a button onClick that calls
// openPinVerification to start the flow
public void openPinVerification(View view) {
    Cotter.PinVerification.startFlow(view, Dashboard.class, "LOGIN");
}
```

{% hint style="info" %}
**Reset PIN** functionality is an **update** that is available starting from **version `0.4.5`**
{% endhint %}

## 🎉 You're done!