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 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 .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.

Why does the SDK not start after integration?

The most common cause is:

  • A malformed VideoCaptureConfiguration.

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:

  1. Create a VideoCaptureConfiguration.
  2. Optionally set a VideoCaptureEventsListener.
  3. Call VideoCapture.start(CaptureEventsListener).

See API and Installation for examples.

Can I build the configuration in code instead of JSON?

Yes. VideoCaptureConfiguration 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 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, and browser is also supported to load texts using the system language. 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: