Configure timeouts
BlinkID limits how long a scanning session can run before it gives up and moves on. This prevents the camera from staying open indefinitely when a user is struggling to capture a document.
How timeouts work
Every platform exposes two timeouts:
Step timeout
The step timeout is a hard deadline for a single scanning step, such as the front side, the back side, or a barcode scan. It starts when the step begins and resets on every side change. While an onboarding or help dialog is showing, the timer pauses.
By default it is 60 seconds.
Inactivity timeout
The inactivity timeout fires when scanning has stopped making visible progress. The timer resets every time the UI state changes, so a user who keeps moving the document toward a successful capture never hits it. It only fires when the user is stuck on the same state for too long.
By default it is 10 seconds.
The inactivity timer does not run during barcode scanning, which can legitimately stay in the same UI state for a while.
Partially supported barcode timeout (web only)
The web SDK exposes one additional timeout, partiallySupportedBarcodeResolveTimeoutMs (8 seconds by default).
When BlinkID detects a barcode whose parsing it does not support, this timer governs how long it keeps trying before resolving the barcode step and moving on.
Configure timeouts
The two timeouts have slightly different names and live in a different settings object on each platform, but they map onto the same two concepts:
| Concept | Web | Android | iOS |
|---|---|---|---|
| Step timeout | scanStepTimeoutMs | stepTimeoutDuration | stepTimeoutDuration |
| Inactivity timeout | inactivityTimeoutMs | stateBasedTimeoutDuration | inactivityTimeoutDuration |
Web and Android express durations in milliseconds; iOS expresses them in seconds.
The example below raises the step timeout to 90 seconds and the inactivity timeout to 15 seconds.
- Web (TS)
- Android (Kotlin)
- iOS (Swift)
On the web, timeouts are part of the UX manager options, not the scanning settings.
Pass them through uxManagerOptions.timeoutConfiguration when creating the component.
const blinkId = await createBlinkId({
uxManagerOptions: {
timeoutConfiguration: {
scanStepTimeoutMs: 90_000,
inactivityTimeoutMs: 15_000,
},
},
});
You can also read and update the configuration at runtime with getTimeoutConfiguration() and setTimeoutConfiguration() on the UX manager.
On Android, timeouts are part of BlinkIdUxSettings, which is separate from BlinkIdSessionSettings.
BlinkIdCameraScanningScreen(
blinkIdSdk = blinkIdSdk,
uxSettings = BlinkIdUxSettings(
stepTimeoutDuration = 90000.milliseconds,
stateBasedTimeoutDuration = 15000.milliseconds,
)
)
On iOS, timeouts are part of the session settings and are expressed in seconds.
let sessionSettings = BlinkIDSessionSettings(
stepTimeoutDuration: 90,
inactivityTimeoutDuration: 15
)
Disable a timeout
You can disable either timeout so that scanning never times out on that condition. The value that disables a timeout differs per platform.
- Web (TS)
- Android (Kotlin)
- iOS (Swift)
Set the timeout to null.
uxManagerOptions: {
timeoutConfiguration: {
scanStepTimeoutMs: null,
inactivityTimeoutMs: null,
},
},
Any other value must be a positive number; zero or a negative value throws an error.
Set the duration to Duration.ZERO.
import kotlin.time.Duration
BlinkIdUxSettings(
stepTimeoutDuration = Duration.ZERO,
stateBasedTimeoutDuration = Duration.ZERO,
)
Set to a value less than zero.
let sessionSettings = BlinkIDSessionSettings(
stepTimeoutDuration: -1,
inactivityTimeoutDuration: -1
)