Wizard
This component can be found under the Sybrin.Document
namespace and is called WizardComponent
.
Full name: Sybrin.Document.WizardComponent
.
It is a component that wraps and orchestrates the rest of the document capture components.
As the user interacts with components housed within the wizard component, it will automatically progress and keep track of steps.
Initialization
The wizard component can be initialized using the following code:
The Sybrin Web SDK provides the option to either provide the ID of the element you wish to use for component initialization, or to provide the element directly.
Please note that 'wizard' is just an example in this context and the ID may be changed as desired as long as it matches the value provided during component initialization in JavaScript.
During initialization, the wizard component allows for a number of configuration options that may be provided using an object literal. The parameters that may be used on the object include the following:
Required:
id (string)
: ID of the element you wish to use for component initialization. Not required ifelement
is provided.element (HTMLElement)
: Element you wish to use for component initialization. Not required ifid
is provided.api (Sybrin.Document.Api)
: Instance of a JavaScript API that may be pre-configured as desired. Not required if an instance ofoptions
is passed.options (Sybrin.Document.Options)
: Configuration options to instantiateSybrin.Document.Api
with. Not required if an instance ofapi
is passed.
Optional:
cameraDirectionPriority (number)
: This property is used to determine which camera direction the SDK should try to prioritize. 0 is none, meaning it will always prompt device selection. 1 is front, meaning it will default to the front camera if only one front device is found. 2 is back, meaning it will default to the rear camera if only one rear device is found.correlationId
: Sets the correlation ID for the case that will be provided with the OCR request. Used for advanced tracking and backend data sync.countries (Sybrin.Document.Country[])
: Explicit country filter to be used by the country select component. Please see country overrides & filtering for details.cropSelectionStart (Sybrin.Document.CropSelectionStart)
: Sets how the crop selection area should be initialized. The options are middle (0) and full (1). The middle option sets the crop selection area to start as a smaller block in the center of the image. The full option will initially select the entire image.defaultDocumentType (string)
: The type of document that must be selected by default.defaultCountry (string)
: The country code of the country that must be selected on the Country Select component by default.documentTypes (Sybrin.Document.DocumentType[])
: Explicit document type filter to be used by the document select component. Please see document type overrides & filtering for details.enableOcr (boolean)
: Sets whether or not OCR must be executed by the Result component.imageCaptureFormat (string: 'jpeg')
: Sets the format that the images will be captured in. Defaults to JPEG.imageUploadFormat (string: 'original' | 'jpeg')
: Sets the format that images will be converted to for upload. Defaults to original.initialImages (string[])
: Sets the initial collection of images to be processed. This is useful if the SDK is being used as a standalone component for image cropping, rotation, and other processing purposes.processComponentHideBack (boolean)
: Sets whether or not the back button must be hidden on the document processing component. Default false.readonlyMode (boolean)
: Disables all events if true. Default false.steps (string)
: A collection of strings to specify/override the steps that the wizard should display, as well as their order. The string values may be:'country-select'
to specify the country select component.'document-select'
to specify the document select component.'prepare'
to specify the prepare component.'device-select'
to specify the device select component.'document-capture'
to specify the document capture component.'document-processing'
to specify the document processing component.'result'
to specify the result component.
selectedDocumentTypeName (string)
: The default document type name code to use if the document select component is excluded as a step in the wizard component.selectedDocumentTypeId (string)
: The default ID that points to a unique document type for a specific country if both the country select component and the document select component are excluded as a step in the wizard component. Can be used as a singular alternative to providingselectedCountryCode
andselectedDocumentTypeName
.selectedCountryCode (string)
: The default country code to use if the country select component is excluded as a step in the wizard component.translations ({ [key: string]: string })
: An object literal representing a dictionary lookup that will be used for translating the component. Please see the translations section on this page for a list of all translatable text, as well as the localization page for a detailed description on how to implement localization.Added configurable property to Wizard component for toggling title display on or off.
Warning: Initialization will fail if the intended host element does not exist yet.
Always ensure that the initialize function is only called after the DOM is loaded.
Destruction
The wizard component may be removed from the UI by calling the destroy()
function on it.
Example:
Functions
Initialize
initialize(): Promise<void>
Initializes the component's DOM and events. The initialization function is asynchronous.
Destroy
destroy(): void
Destroys the component's DOM and events.
Set Correlation ID
setCorrelationId(correlationId: string): void
Sets the correlation ID to the provided value.
Set Translations
setTranslations(translations?: { [key: string]: string; }): void
Changes the component's translations to the provided values and updates the DOM accordingly.
Get Current Step
getCurrentStep(): StepType
Gets the step that is currently active in the wizard. StepType is:
"country-select" | "document-select" | "prepare" | "device-select" | "document-capture" | "document-processing" | "result";
Back
back(): void
Signals to the wizard to revert to the previous step.
Next
next(): void
Signals to the wizard to proceed to the next step.
Events
The wizard component offers multiple events. To hook onto an event, simply assign a function to it.
The following options are available:
onWizardDone(result: DocumentCaptureResult)
onBeforeStepChanged(oldStep: string, newStep: string)
onAfterStepChanged(oldStep: string, newStep: string)
onCountrySelected(alpha3Code: string, alpha2Code: string, numericCode: string)
onDocumentSelected(documentTypeName: string, documentTypeId: string)
onCaptureResult(result: DocumentCaptureResult)
onCaptureError(error: string)
onCaptureCancelled()
onBeforeCapture()
onBeforeUpload()
onViewPrivacyPolicy()
On Wizard Done
This function is called when all wizard steps have been completed and a result was acquired without error. To hook onto the event, you may use the following code:
The result parameter is of type Sybrin.Document.DocumentCaptureResult
and includes the following properties:
ocrResults (DocumentOcrResult[])
: The array of document OCR result instances representing the data that was read from the images.documentType (string)
: The document type name string of the document type that was selected during the journey.countryCode (string)
: The Alpha-3 standard country code of the country that was selected during the journey.correlationId (string)
: The unique identifier used for advanced tracking and backend data synchronization.documentImage (string[])
: Base64 string array of the processed photos of the document (if the document crop component was used).originalDocumentImages (string[])
: Base64 string array of the original photos of the document.message (string)
: Additional information when applicable, for instance an error message if one occurred.facingMode (string)
: The facing direction of the camera used during capture.success (boolean)
: Whether or not the document was captured successfully.
On Before Step Changed
This function is called before the wizard changes to another step. This includes progressing forward or going back to a previous step. To hook onto the event, you may use the following code:
The oldStep parameter is of type string
.
The newStep parameter is of type string
.
On After Step Changed
This function is called after the wizard changed to another step. This includes progressing forward or going back to a previous step. To hook onto the event, you may use the following code:
The oldStep parameter is of type string
.
The newStep parameter is of type string
.
On Country Selected
This event bubbles the onCountrySelected
event up once it executes on the country select component.
On Document Selected
This event bubbles the onDocumentSelected
event up once it executes on the document select component.
On Capture Result
This event bubbles the onCaptureResult
event up once it executes on the document capture component.
On Capture Error
This event bubbles the onCaptureError
event up once it executes on the document capture component.
On Capture Cancelled
This event bubbles the onCaptureCancelled
event up once it executes on the document capture component.
On Before Capture
This event bubbles the onBeforeCapture
event up once it executes on the document capture component.
On Before Upload
This event bubbles the onBeforeUpload
event up once it executes on the prepare component.
On View Privacy Policy
This event bubbles the onViewPrivacyPolicy
event up once it executes on the prepare component.
Styling
The wizard component is structured a follows:
Since the wizard component has no visual elements by itself, no styling is necessary. Please style individual components housed within the wizard instead.
Translations
The translations provided to this component are in turn provided to the internal components hosted by it. Please see individual component translation sections for details on which translation keys are available to them, and also the localization section for an overview on available keys and how to make use of localization functionality.
Last updated