FAQs & Known issues¶

FAQs¶

Which iOS versions are supported?¶

The SDK supports iOS 13.0 and later. See Specifications.

What permissions do I need to request?¶

The standard document capture flow requires:

Camera permission to capture document images.

Make sure your app defines NSCameraUsageDescription in Info.plist. See Installation and Specifications.

How do I integrate the SDK?¶

The SDK is integrated using the zipped .xcframework files.

Add all required frameworks to the Xcode target.
Set them to Embed & Sign.

See Installation.

Why does the SDK not start after integration?¶

The most common causes are:

Missing NSCameraUsageDescription in Info.plist.
A malformed DocumentCaptureConfiguration.
Missing bundled JSON files when loading configuration from the app bundle.
Frameworks not added correctly to the target.

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:

Create a DocumentCaptureConfiguration.
Optionally set a DocumentCaptureEventsDelegate.
Call DocumentCapture.start(delegate:config:).

See API and Installation for examples.

Can I build the configuration in code instead of JSON?¶

Yes. DocumentCaptureConfiguration is Codable, so it can be:

Built directly in Swift 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:

DocumentCaptureDelegate for result and lifecycle callbacks.
DocumentCaptureEventsDelegate for optional tracking events through onDocumentCaptureEvent(event:).

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¶

UIKit projects may require disabling User Script Sandboxing¶

If the host app is UIKit-based, disable User Script Sandboxing in Xcode Build Settings as described in the installation guide. See Installation.

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: