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 SDK requires:

Camera permission to capture the user's face and document.
Microphone permission to record the user saying their full name.

Make sure your app defines both NSCameraUsageDescription and NSMicrophoneUsageDescription in Info.plist.

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.

Why does the SDK not start after integration?¶

The most common causes are:

Missing camera or microphone usage descriptions in Info.plist.
A malformed VideoCaptureConfiguration.
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 onVideoCaptureFinished(error:) and any event reported through onVideoCaptureEvent(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 VideoCaptureConfiguration.
Optionally set a VideoCaptureEventsDelegate.
Call VideoCapture.start(delegate:config:).

See API and Installation for examples.

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

Yes. VideoCaptureConfiguration 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 its default value.

If a property is present but has an invalid type or unsupported value, validation can 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 allows you to 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 default built-in 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 change the camera used by the SDK?¶

No. According to the current specifications, the SDK launches the front camera by default and this behavior cannot be changed by configuration. 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 35,000 to 120,000 ms. See detectionTimeout.

How do I receive SDK lifecycle events?¶

Implement:

VideoCaptureDelegate for result and lifecycle callbacks.
VideoCaptureEventsDelegate for optional tracking events through onVideoCaptureEvent(event:).

See API.

What is the difference between `onVideoCaptureResults` and `onVideoCaptureEvent`?¶

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

Use onVideoCaptureResults for business completion logic and onVideoCaptureEvent 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.

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 will stop instead of silently ignoring the issue.

This is expected behavior. Validate custom JSON carefully before shipping it.

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.

Legacy-to-current migration mapping is still incomplete¶

The legacy migration table is currently partial. Not every historical key from Video 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: