Skip to content

FAQs & Known issues

FAQs

Which Android versions are supported?

The SDK supports Android 10 and later. See Specifications.

  • Minimum SDK version: 29 (Android 10)

What permissions do I need to request?

The standard document capture flow requires:

  • Camera permission to capture document images.

How do I integrate the SDK?

The SDK is integrated using the zipped .aar files.

  1. Import all provided .aar libraries into the app/libs directory:
  2. Add the SDK libraries to the app build.gradle dependencies:
  3. Add the required Jetpack Compose dependencies.
  4. Add the required external dependencies.

See Installation.

Why does the SDK not start after integration?

The most common cause is:

  • A malformed DocumentCaptureConfiguration.

If startup fails, check the error received in onDocumentCaptureFinished(error:) and any event reported through onDocumentCaptureEvent(event:). Invalid or malformed configuration values can also stop the SDK during startup. See API and Configuration.

How do I start the SDK?

The standard flow is:

  1. Create a DocumentCaptureConfiguration.
  2. Optionally set a DocumentCaptureEventsListener.
  3. Call fun start(listener: DocumentCaptureListener, configuration: DocumentCaptureConfiguration, context: Context).

See API and Installation for examples.

Can I build the configuration in code instead of JSON?

Yes. DocumentCaptureConfiguration is a data class, so it can be:

  • Built directly in Kotlin code.
  • Decoded from a JSON file.

Both approaches are supported. See Installation.

What happens if a configuration field is missing?

If a property is omitted, the SDK uses the documented default value for that field.

If a property is present but has an invalid type or unsupported value, configuration validation may fail and the flow can stop during startup. See Configuration and API.

Can I customize texts, styles, and media?

Yes. The SDK configuration is organized into four top-level areas:

  • setup
  • texts
  • styles
  • medias

This structure lets you separate behavior, wording, visual customization, and assets. See Customization and Migration guide.

Do I need to provide all texts if I want a custom language?

Yes. If you want to support a language other than the built-in defaults, you should provide the full custom texts configuration.

The built-in default languages are Spanish and English. See Configuration and Customization.

Can I hide the instructions screen?

Yes, using setup.instructionsShow = false.

However, this is only recommended if your app already provides equivalent guidance before the SDK starts. See instructionsShow.

Can I hide the SDK close button?

Yes, using setup.closeButtonShow = false.

That said, keeping the built-in close button visible is recommended unless your integration already provides a clear and reliable exit mechanism. See closeButtonShow.

Can I hide the capture headings?

Yes, using setup.captureHeadingShow = false.

This is not generally recommended because it can reduce clarity and accessibility for end users. See captureHeadingShow and Accessibility.

Can I change the camera used by the SDK?

No. For the document flow described in this documentation, the SDK uses the back camera to capture document images. Camera behavior should follow the documented specifications. See Specifications.

What document types can I configure?

Use setup.documents to define the expected document.

It can point to:

  • A specific supported document type.
  • A supported document group.

See documents.

What is detectionTimeout and which values are valid?

detectionTimeout defines how long the SDK waits before stopping the process automatically.

The accepted range is 60,000 to 300,000 ms. See detectionTimeout.

How do I receive SDK lifecycle events?

Implement:

  • DocumentCaptureListener for result and lifecycle callbacks.
  • DocumentCaptureEventsListener for optional tracking events through onDocumentCaptureEvent(event: DocumentCaptureEvent).

See API.

What is the difference between onDocumentCaptureResults and onDocumentCaptureEvent?

  • onDocumentCaptureResults(results:) provides the final successful SDK result.
  • onDocumentCaptureEvent(event:) provides intermediate lifecycle and tracking events generated during the flow.

Use onDocumentCaptureResults for business completion logic and onDocumentCaptureEvent for logging, analytics, or debugging. See API.

Known issues

Invalid configuration values fail at runtime

The SDK validates the received configuration when starting. If a property has an invalid type or unsupported value, the flow may stop instead of silently ignoring the issue.

This is expected behavior. Validate custom JSON carefully before shipping it. See Configuration and API.

Hiding instructional UI can reduce usability

Disabling elements such as the instructions screen, capture headings, or help modal may negatively affect comprehension and accessibility.

If these elements are hidden, the host application should provide an equivalent user guidance experience. See Accessibility.

Legacy-to-current migration mapping is still incomplete

The legacy migration table is currently partial. Not every historical key from Document SDK has been documented yet, especially in the styling area.

If a legacy parameter is not listed, use the current references as the source of truth: