# 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](/files/-M0Ray-M6mEFhHMiUl5r)

## Steps

1. [Import Cotter as a dependency](/sdk-reference/android/android-sdk-2.md#step-1-import-cotter-as-a-dependency)
2. [Set allowed Authentication Methods](/sdk-reference/android/android-sdk-2.md#step-2-setting-authentication-methods) in the Dashboard
3. [Create a User](/sdk-reference/android/android-sdk-2.md#step-3-creating-a-user)
4. [Initialize Cotter](/sdk-reference/android/android-sdk-2.md#step-4-initialize-cotter) in your Main Activity
5. [Enroll Biometrics and PIN](/sdk-reference/android/android-sdk-2.md#step-5-enroll-biometric-and-pin): PIN is recommended as a fallback method
6. [Verify Biometrics](/sdk-reference/android/android-sdk-2.md#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](/files/-M0Rd71oJbeus4CzKUIm)

{% 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](/api-reference/user-api.md#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](/api-reference/user-api.md#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](/files/-M0Ri4hUvJsW7AYs-tt-)

### **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](/api-reference/reset-pin-api.md) 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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cotter.app/sdk-reference/android/android-sdk-2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.