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

If startup fails, check the error received in onSelfieCaptureFinished(error:) and any event reported through onSelfieCaptureEvent(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 SelfieCaptureConfiguration.
  2. Optionally set a SelfieCaptureEventsListener.
  3. Call SelfieCapture.start(listener: SelfieCaptureListener, configuration: SelfieCaptureConfiguration, context: Context).

See API and Installation for examples.

Can I build the configuration in code instead of JSON?

Yes. SelfieCaptureConfiguration 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, 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 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 hide the help modal?

Yes, using setup.helpModalShow = false.

Only do this if the host app already provides enough guidance to complete the flow without the built-in help. See helpModalShow.

Which camera does Selfie SDK use?

By default, the SDK uses the front camera.

You can set setup.selectCamera to front or back, but active liveness must use front. See selectCamera and Specifications.

Is a challenge token always required?

No.

  • setup.liveness = "passive": token is not required.
  • setup.liveness = "active": a challenge token is required.

If the token expires during active flow, use SelfieCapture.setChallengeToken(challengeToken:). See Configuration and API.

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:

  • SelfieCaptureListener for result and lifecycle callbacks.
  • SelfieCaptureEventsListener for optional tracking events through onSelfieCaptureEvent(event: SelfieCaptureEvent).

See API.

What is the difference between onSelfieCaptureResults and onSelfieCaptureEvent?

  • onSelfieCaptureResults(results: SelfieCaptureResult) provides the final successful SDK result.
  • onSelfieCaptureEvent(event: SelfieCaptureEvent) provides intermediate lifecycle and tracking events generated during the flow.

Use onSelfieCaptureResults for business completion logic and onSelfieCaptureEvent for logging, analytics, or debugging. See API.

What is onChallengeTokenRequired() used for?

onChallengeTokenRequired() notifies the host app that the active flow needs a valid challenge token to continue.

This callback is relevant for active liveness integrations. After obtaining a fresh token, update it through SelfieCapture.setChallengeToken(challengeToken: String). See API and Configuration.

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.

Active liveness requires a valid challenge token

If setup.liveness is set to active and the challenge token is missing, expired, or invalid, the flow cannot continue correctly.

Make sure the token lifecycle is handled by the host app and refreshed when onChallengeTokenRequired() is triggered. 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 Selfie 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: