# Signature

The Signature module captures a signature the user hand-draws on screen, optionally presenting documents to sign. 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. When the app defines the steps in code, you add the module to an `IncdOnboardingFlowConfiguration` as shown below; when the flow is defined in Dashboard, you reference it and let the back end drive the steps. See [Integration Approaches](https://developer.incode.com/docs/ios-flow-configuration).

**Availability:** All variants.

## Add Signature

Add the module with `addSignature()`. You can call it with no arguments to add the module with its defaults, or [pass values](#configuration-options) to customize it.

```swift
flowConfig.addSignature()
```

### Example

The example below adds a Signature module and presents documents for the user to sign.

```swift
flowConfig.addSignature(
    descriptionMaxLines: nil,
    documents: [
        SignDocument(
            title: "Terms",
            fileURL: contractURL,
            signaturePositions: [/* SignaturePosition */]
        )
    ]
)
```

## Configuration Options

Configure the module with `addSignature()`.

| Option                | Type             | Notes                                                                                                             |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `descriptionMaxLines` | `Int?`           | Sets the maximum number of lines for the description text.                                                        |
| `documents`           | `[SignDocument]` | Presents documents for signing. Each `SignDocument` has a `title`, a `fileURL`, and its `signaturePositions`.     |
| `title`               | `String?`        | **Deprecated.** Sets the title shown on the Signature screen. Provide it via `Localizable.strings` instead.       |
| `description`         | `String?`        | **Deprecated.** Sets the description shown on the Signature screen. Provide it via `Localizable.strings` instead. |

The `addSignature(title:description:descriptionMaxLines:documents:)` overload is **deprecated**: the `title` and `description` parameters should be customized via `incdOnboarding.signature.title` and `incdOnboarding.signature.description` in your `Localizable.strings` (see [Localize Display Text](https://developer.incode.com/docs/ios-customization#localize-display-text)). Use `addSignature(descriptionMaxLines:documents:)` for new integrations.

## Result

The module delivers a `SignatureFormResult` to the `onSignatureCollected(_:)` callback on your `IncdOnboardingDelegate`.

```swift
func onSignatureCollected(_ result: SignatureFormResult)
```

`SignatureFormResult` fields:

- `signature: UIImage?`: The captured signature image. On iOS, the image data is returned directly, not as a file path or URI.
- `signedDocuments: [SignDocument]?`: The documents that were signed, if any were presented.
- `error: SignatureError?`: Set when the step did not complete successfully; otherwise, `nil`.

## Errors

Failures surface through the `error` field of the result.

`SignatureError` cases:

- `error(_ error: IncdError)`: An underlying error occurred.
- `declinedToSignDocument`: The user declined to sign a presented document.
- `retryLimitReached`: The user exceeded the maximum number of allowed signing attempts.

<br />