# Signature

The Signature module captures a signature the user hand-draws on screen. It is typically placed at the end of a verification journey to capture explicit consent.

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

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 Signature

Add the module with `addSignature()`, or pass a configured instance with `addSignature(signature)`. If you do not need to customize the module, use the no-argument `addSignature()` method instead of building an instance.

```kotlin
flowConfigBuilder.addSignature()
```
```java
flowConfigBuilder.addSignature();
```

### Example

The example below adds a default `Signature` module to the flow and listens for the result through `onSignatureCollected()`.

```kotlin
val signature = Signature.Builder().build()

val flowConfig = FlowConfig.Builder()
    .addSignature(signature)
    .build()

val onboardingListener = object : OnboardingListener() {
    override fun onSignatureCollected(signatureFormResult: SignatureFormResult) {
        // Signature collected. Process the result.
    }
}

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)
```
```java
Signature signature = new Signature.Builder().build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addSignature(signature)
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onSignatureCollected(@NonNull SignatureFormResult signatureFormResult) {
        // Signature collected. Process the result.
    }
};

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

## Configuration Options

Configure the module with `Signature.Builder`. Both options are deprecated in favor of overriding the SDK string resources.

| Setting                                | Description                                                                                                |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `setTitle(int titleResId)`             | Sets the title text shown on the Signature screen. Deprecated; override the string resource instead.       |
| `setDescription(int descriptionResId)` | Sets the description text shown on the Signature screen. Deprecated; override the string resource instead. |

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

## Result

Signature delivers a `SignatureFormResult` to the `onSignatureCollected(SignatureFormResult)` callback on the `OnboardingListener`. Key fields include:

- `signaturePath`: The URI pointing to the captured signature image; `null` when unavailable.
- 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 via `OnboardingListener.onError(Throwable)`. There is no Signature-specific exception subtype.

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