Wizard

This component can be found under the Sybrin.Identity namespace and is called WizardComponent.

Full name: Sybrin.Identity.WizardComponent.

It is a component that wraps and orchestrates the rest of the data extraction 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:

HTML

<div id='wizard'></div>

JavaScript

var options = new Sybrin.Identity.Options({
    apiKey: 'your-api-key-here', 
    authorizationEndpoint: 'your-auth-endpoint-here'
    dataExtractionEndpoint: 'your-data-extraction-endpoint-here'
});

// Option 1: Passing an id
var component = new Sybrin.Identity.WizardComponent({ 
    id: 'wizard',
    options: options
});

// Option 2: Passing a DOM element
var element = document.getElementById('wizard');
var component = new Sybrin.Identity.WizardComponent({ 
    element: element,
    options: options
});

component.initialize();

The Sybrin Web SDK provides the option to either pass down the ID of the element you wish to use for component initialization, or to pass 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 passed down during component initialization in JavaScript.

During initialization, the wizard component allows for a number of configuration options that may be passed down using an object literal. The parameters that may be used on the object include the following:

Required:

• api (Sybrin.Identity.Api): Instance of a JavaScript API that may be pre-configured as desired. Not required if an instance of options is provided.

• element (HTMLElement): Element you wish to use for component initialization. Not required if id is provided.

• id (string): ID of the element you wish to use for component initialization. Not required if element is provided.

• options (Sybrin.Identity.Options): Configuration options to instantiate Sybrin.Identity.Api with. Not required if an instance of api is provided.

Optional:

• allowCameraCapture (boolean): Sets whether or not the Prepare component should allow camera capture. If set to false, the Take Photo button will not be present. The default value is true.

• allowUpload (boolean): Sets whether or not the Prepare component should allow file uploads. If set to false, the Upload button will not be present. The default value is true.

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

• captureMode (number): The mode of capture that should be used. The default value is 0 (automatic). Available modes are as follows:

  • 0 - automatic: The component will automatically try to detect when a document is in position.

  • 1 - manual: The component will let the user manually click or tap a button to capture. The button will be centered at the bottom of the video element.

  • 2 - semiAutomatic: The component will wait for the user to click a button to indicate readiness before it tries to run automatic document detection. The button will be centered at the bottom of the video element.

  • 3 - externalManual: The component will let the user manually click or tap a button to capture. The button will be in the bottom right corner of the component.

  • 4 - externalSemiAutomatic: The component will wait for the user to click a button to indicate readiness before it tries to run automatic document detection. The button will be in the bottom right corner of the component.

• correlationId (string): Unique identifier for the case that will be passed down to the back end if set.

• countries (Sybrin.Identity.Country[]): Explicit country filter to be used by the country select component. Please see country overrides & filtering for details.

• 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.Identity.DocumentType[]): Explicit document type filter to be used by the document select component. Please see document type overrides & filtering for details.

• enableMobileCapture (boolean): Sets whether or not the "Mobile Capture" button should be enabled on the prepare component when the flow is being executed on a desktop browser.

• forceMobileCapture (boolean): Sets whether or not the prepare component should be forced into the mobile capture state by default when it is initialized.

• imageCaptureFormat (string: 'jpeg'): Sets the format that the images will be captured in. Defaults to JPEG.

• isLowConfidenceBlocking (boolean): Sets whether or not the result component's "Next" button should be disabled if there are any unaddressed fields with a low confidence rating. Default true.

• isLowConfidenceConfirmable (boolean): For the result component, sets whether or not the user will be able to click on the warning icon of a low confidence field to mark it as "Confirmed". Default true.

• isLowConfidenceEditable (boolean): For the result component, sets whether or not low confidence fields will become editable so that the user can amend them. Default true.

• isSingleStep (boolean): Sets whether or not the result component's "Next" button should be displayed as "Complete Step" instead.

• priorityCountryCodes (string[]): An array of strings containing ISO-3 standard country codes. These codes are used to designate priority countries, which will be prominently displayed at the top of the Country Select list in the order they appear in this array.

• readonlyMode (boolean): Disables all events if true. Default false.

• selectedCountryCode (string): The default country code to use if the country 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 providing selectedCountryCode and selectedDocumentTypeName.

• selectedDocumentTypeName (string): The default document type name code to use if the document select component is excluded as a step in the wizard component.

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

  • 'scan' to specify the document select component.

  • 'result' to specify the result 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.

• wordConfidenceThreshold (number): For the result component, sets the threshold for a field to be considered low confidence. Any value lower than configured here will be considered low confidence. Default 90.

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:

component.destroy();

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 Translations

setTranslations(translations?: { [key: string]: string; }): void

Changes the component's translations to the provided values and updates the DOM accordingly.

Set Correlation ID

setCorrelationId(value: string): void

Sets the component correlation ID (that will be provided to the JavaScript API and sent to the backend) to the provided value.

Get Current Step

getCurrentStep(): StepType

Gets the step that is currently active in the wizard. StepType is:

"prepare" | "device-select" | "country-select" | "document-select" | "scan" | "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.

Initialize Mobile Capture With URL

initializeMobileCaptureWithUrl(url: string): void

Switches the Prepare component to mobile mode with a generated QR code using the provided URL.

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: DocumentScanResult)

• onBeforeStepChanged(oldStep: string, newStep: string)

• onAfterStepChanged(oldStep: string, newStep: string)

• onScanResult(result: DocumentScanResult)

• onScanError(error: string)

• onScanCancelled()

• onBeforeScan()

• onBeforeUpload()

• onCountrySelected(alpha3Code: string, alpha2Code: string, numericCode: string)

• onDocumentSelected(documentTypeName: string, documentTypeId: string)

• onMobileCaptureStart()

• onMobileCaptureCancel()

• 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:

component.onWizardDone = function(result) {
    console.log('Success: ', result.success);
}

The result parameter is of type DocumentScanResult and includes the following properties:

• success (boolean): Whether or not data could be extracted.

• data (object): An object with all data fields that were successfully extracted.

• fieldEditMode (FieldEditMode): The kind of editing mode applied to the result component's fields. 0 = include, meaning no fields except for the fields in the field list should be editable (included). 1 = exclude, meaning all fields except for the fields in the field list should be editable (excluded). Default 0

• fieldList (string[]): List if fields to either include in or exclude from editable fields.

• wordConfidenceResults (object): An object behaving as a dictionary where the key is a string corresponding to the field name and the value is a number value representing the confidence value that the field was extracted correctly.

• originalValues (object): An object behaving as a dictionary where the key is a string corresponding to the field name and the value is a string value representing the original value of the field before it was edited.

• images (object): An object with images. These include

  • croppedFrontImage (string): Base64 string of the front image after backend cropping was applied. This cropping algorithm attempts to crop out only the document itself.

  • croppedBackImage (string): Base64 string of the back image after backend cropping was applied. This cropping algorithm attempts to crop out only the document itself.

  • documentImage (string): Base64 string of the front photo of the document.

  • documentBackImage (string): Base64 string of the back photo of the document (if supplied).

  • portraitImage (string): Base64 string of the extracted face portrait image pulled from the document.

The editedValues parameter is an object literal, acting as a key-value pair dictionary. This object is populated with a list of all values on the result that were edited. It is up to the parent component to apply or discard the changes as necessary.

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:

component.onBeforeStepChanged = function(oldStep, newStep) {
    console.log('The old step is: ', oldStep);
    console.log('The new step will be: ', newStep);
}

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:

component.onAfterStepChanged = function(oldStep, newStep) {
    console.log('The old step was: ', oldStep);
    console.log('The new step is: ', newStep);
}

The oldStep parameter is of type string.

The newStep parameter is of type string.

On Scan Result

This event bubbles the onScanResult event up once it executes on the document scan component.

On Scan Error

This event bubbles the onScanError event up once it executes on the document scan component.

On Scan Cancelled

This event bubbles the onScanCancelled event up once it executes on the document scan component.

On Before Scan

This event bubbles the onBeforeScan event up once it executes on the document scan component.

On Before Upload

This event bubbles the onBeforeUpload event up once it executes on the document scan component.

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 Mobile Capture Start

This event bubbles the onMobileCaptureStart event up once it executes on the prepare component.

On Mobile Capture Cancel

This event bubbles the onMobileCaptureCancel 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:

<div class="sybrin-identity-wizard sybrin-sdk-wizard">
    <div class="sybrin-identity-wizard-viewport sybrin-sdk-wizard-viewport">
    </div>
</div>

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.