# AES (Advanced Electronic Signature)

The AES (Advanced Electronic Signature) module shows the user documents to sign, collects their consent, and captures a certificate-backed electronic signature. That digital certificate verifies their identity, making the signed document legally binding and compliant.

For an overview of this module and how it works, see [Advanced Electronic Signature](https://developer.incode.com/docs/advanced-electronic-signature).

How you use this module depends on your [integration pattern](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). In Patterns 1 and 2, you add the module to a `FlowConfig` in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with `startFlow()` or `startWorkflow()` as shown on [Run Flows Configured in Dashboard](https://developer.incode.com/docs/android-run-flows-configured-online).

## Add AES

1. Add the [ID Scan](https://developer.incode.com/docs/android-id-scan), [Selfie Scan](https://developer.incode.com/docs/android-selfie-scan), and [Phone](https://developer.incode.com/docs/android-phone) modules before AES. They can be added in any order, but all three must be present in the flow. Calling `addAES` without these prerequisites throws `ModuleConfigurationException`.
2. Add the module with `addAES()` (default config) or `addAES(aes)` (custom config):

   ```kotlin
   flowConfigBuilder.addAES()
   // or with a configured instance:
   flowConfigBuilder.addAES(aes)
   ```
   ```java
   flowConfigBuilder.addAES();
   // or with a configured instance:
   flowConfigBuilder.addAES(aes);
   ```

### Example

The example below builds a custom `AES` configuration that shows the upload screen and downloads the signed PDF, adds the required ID Scan, Selfie Scan, and Phone modules ahead of it, and listens for the result through `onAESCompleted()`.

```kotlin
val aes = AES.Builder()
    .setUploadDocument(true)
    .setDownloadDocument(true)
    .build()

val flowConfig = FlowConfig.Builder()
    .addID()
    .addSelfieScan()
    .addPhone()
    .addAES(aes)
    .build()

val onboardingListener = object : OnboardingListener() {
    override fun onAESCompleted(aesResult: AESResult) {
        // AES step finished. Process the result.
    }
}

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)
```
```java
AES aes = new AES.Builder()
    .setUploadDocument(true)
    .setDownloadDocument(true)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addID()
    .addSelfieScan()
    .addPhone()
    .addAES(aes)
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onAESCompleted(@NonNull AESResult aesResult) {
        // AES step finished. Process the result.
    }
};

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener);
```

## Configuration Options

Configure the module with `AES.Builder`.

| Setting                        | Description                                                                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `setUploadDocument(Boolean)`   | If `true`, shows the AES upload screen before the normal AES screens. Defaults to `false`.                                         |
| `setDownloadDocument(Boolean)` | If `true`, downloads signed PDFs and shows the Confirmed Signature Details screen at the end of the AES flow. Defaults to `false`. |

For the complete option set, see `AES.Builder` in [API Reference](https://developer.incode.com/docs/android-api-reference).

## Result

AES delivers an `AESResult` to the `onAESCompleted(AESResult)` callback on the `OnboardingListener`. Key fields include:

- `documentSigning`: `true` if the document was signed using an advanced electronic signature.
- `resourcesNotFound`: `true` if the required signing resources could not be found.
- Fields inherited from `BaseResult`:
  - `resultCode`: The `ResultCode` for this result.
  - `error`: When `ResultCode` is `ERROR`, the `Throwable` that caused it; otherwise, `null`.
  - `deviceStats`: The `DeviceStats` snapshot of the device state when the result was produced.
  - `motionStatus`: Device motion assessment during capture. One of the following:
    - `UNCLEAR`: Motion could not be determined; the default.
    - `PASS`: Device motion was within acceptable limits.
    - `FAIL`: Excessive device motion was detected.

If the step fails, the error surfaces through `OnboardingListener.onError(Throwable)`.

For all fields, see `AESResult` in [API Reference](https://developer.incode.com/docs/android-api-reference).