> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/authentication/custom/sdk/android-sdk/integration-overview.md).

# Integration Overview

### Overview

The authentication process involves creating a request data transfer object (`AuthenticatorRequestDTO`), setting necessary parameters, and calling the `authenticate` method on the `VidaAuthenticator`. 

The result of this asynchronous call is handled via callbacks in an `AuthenticationStatusListener`

A detailed explanation of each method is given below

### **AuthenticatorRequestDTO**

A Data Transfer Object (DTO) used to encapsulate the parameters required for the authentication process.

**Parameters**:

* **API Key**: A unique key provided to authenticate the API request.
* **License Key**: A key provided to verify the application's license.
* **AuthEventID**: An identifier for the authentication event.
* **Language ID** (Optional): The language code (e.g., "en" for English) for localisation purposes.
* **Liveness Retry** (Optional):  Enable or disable the liveness retry feature, which attempts to recapture a live image in case of capture failures. This feature is disabled by default

```java
AuthenticatorRequestDTO requestDTO = new AuthenticatorRequestDTO();
requestDTO.setApiKey(KeyConstant.API_KEY);
requestDTO.setLicenseKey(KeyConstant.LICENSE_KEY);
requestDTO.setLanguageId("en");
requestDTO.setAuthEventID("authEventId");
requestDTO.setLivenessRetry(true); 
```

### **VidaAuthenticator.authenticate()**

This method initiates the authentication process. It is asynchronous and uses callbacks to handle the result.

**Parameters**:

* **WeakReference to Activity**: A weak reference to the current Activity to avoid memory leaks.
* **AuthenticatorRequestDTO**: An instance containing all the necessary authentication parameters.
* **AuthenticationStatusListener**: A listener interface to handle the success, error, and state change callbacks.

```java
VidaAuthenticator.authenticate(new WeakReference<>(MainActivity.this), requestDTO, new AuthenticationStatusListener<>());
```

### **AuthenticationStatusListener**

An interface to handle the outcomes of the authentication process.

**Methods**:

* **onSuccess(JSONObject result)**: Called when authentication is successful. The `result` parameter contains the authentication result in JSON format.
* **onError(int errorCode, String errorMessage)**: Called when an error occurs during authentication. The `errorCode` and `errorMessage` parameters provide details about the error.
* **onStateChanged(ProcessState state)**: Called to handle changes in the authentication process state. The `state` parameter indicates the current state of the process.

### Sample Code

```java
import id.vida.auth.v2.VIDAAuthException;
import id.vida.auth.v2.VidaAuthenticator;
import id.vida.auth.v2.dto.AuthenticatorRequestDTO;
import id.vida.auth.v2.listeners.AuthenticationStatusListener;
import id.vida.auth.v2.utils.ProcessState;

AuthenticatorRequestDTO requestDTO = new AuthenticatorRequestDTO();
requestDTO.setApiKey(KeyConstant.API_KEY);
requestDTO.setLicenseKey(KeyConstant.LICENSE_KEY);
requestDTO.setLanguageId("en");
requestDTO.setAuthEventID("authEventId");
requestDTO.setLivenessRetry(true); // Optional: only to enble liveness retries.

try {
    VidaAuthenticator.authenticate(new WeakReference<>(MainActivity.this), requestDTO, new AuthenticationStatusListener<>() {
        @Override
        public void onSuccess(JSONObject result) {
            // customer action on result 
        }

        @Override
        public void onError(int errorCode, String errorMessage) {
            // customer action on failures
        }

        @Override
        public void onStateChanged(ProcessState state) {
            // Handle authentication state changes if needed
        }
    });
} catch (VIDAAuthException e) {
    // Handle authentication errors
    // Customer action on errors
}
```