Constructing your Configuration JSON using JSON Schemas

The following pages will walk you through using the provided JSON Schemas to effectively configure (ScanViewConfig) and interpret the results (PluginResult) of your integration of the Mobile SDK.

If you understand the concepts on this page, you can jump directly to

What are the provided JSON Schemas?

Think of JSON Schemas as blueprints. They define the structure, required properties, and acceptable data types within a JSON file. This ensures compatibility and helps you avoid errors when configuring scans and interpreting results.

ScanViewConfig and PluginResult Schemas

There are two key schemas provided to work with:

  1. ScanViewConfig Schema: This schema defines the configuration options you can use when initiating a scan. Each option is explained in detail, including its purpose, allowed values, and whether it’s required (or optional, if not marked as required).

  2. PluginResult Schema: This schema describes the format of the JSON you’ll receive after a scan completes. Understanding this schema will enable you to extract and utilize the scan results effectively.

ScanViewConfig Schema

The ScanViewConfig is required to configure the Mobile SDK for a specific use case. It contains sub-configurations (such as the PluginConfig, CameraConfig, FlashConfig, etc). Most of those are optional, some are required. The required ones are marked as such (Keyword: required). If an optional config is not provided, the Mobile SDK will select appropriate default values instead.

It is recommended to start implementing your use case with a ScanViewConfig as provided by our Developer Examples (on Github).

Each ScanViewConfig is required to have one config of the following types:

  • viewPluginConfig: Use this config for a simple use case that only requires one ScanPlugin. One scan will yield one result.

  • viewPluginCompositeConfig: Use this config for combining multiple ScanPlugins into more involved workflows. One scan might yield one or more results, depending on your processingMode.

    • processingMode: "sequential": Combine multiple ScanPlugins to retrieve multiple PluginResults sequentially. Scanning will be started with the first ScanPlugin in the config and continued sequentially in the order with which the ScanPlugins are defined in the config.

    • processingMode: "parallel": Combine multiple ScanPlugins to retrieve multiple PluginResults. Scanning will be started with all defined ScanPlugins at the same time. Scanning is finished when the last ScanPlugin has yielded a result.

    • processingMode: "parallelFirstScan": Combine multiple ScanPlugins and retrieve the data from the ScanPlugin that returns the result first. Use this ProcessingMode to receive data that is available as Barcode and Text, e.g. the same Vehicle Identification Number is usually displayed as Text and Barcode.

Below is a rough outline of the structure of a ScanViewConfig:

  • ScanViewConfig (using one ScanPlugin)

    • cameraConfig: Configure camera parameters, e.g. captureResolution, zoomGesture, etc.

    • flashConfig: Configure flash parameters, e.g. mode, alignment, imageOn, etc.

    • viewPluginConfig: Configure a group of configurations relating to your use case

      • pluginConfig (required): Configure which ScanPlugin to use for your use case, e.g. tinConfig or vinConfig or meterConfig or barcodeConfig (to name a few options). id is a required property in any case, as it sets how to identify your which plugin returned a result.

      • cutoutConfig: Configure the cutout area parameters, e.g. alignment, cornerRadius, strokeWidth, etc.

      • scanFeedbackConfig: Configure sensory, auditory, and visual feedback, e.g. vibrateOnResult, beepOnResult, style, animation, fillColor, etc.

      • uiFeedbackConfig: Configure UI feedback to enhance your scanning experience via presets and customizing those presets, e.g. presets, elements.

    • options: Not used for Mobile SDK. Only used in combination with Plugin for [Flutter/Cordova/React Native]

For completeness, the below structure represents the possible structure of a ScanViewConfig of a more complex use case using multiple ScanPlugins. Keep in mind that when using a sequential processingMode, the order of the ScanPlugins defines the order of the sequential execution.

  • ScanViewConfig (using multiple ScanPlugins)

    • viewPluginComposite (required): Configure multiple ScanPlugins into your defined workflow. Contains a processingMode and an ordered list of viewPlugins.

      • processingMode: Configure the order of execution of your ScanPlugins, e.g. sequential, parallel, parallelFirstScan.

      • viewPlugins: Configure the list of ScanPlugins to use. In the case of sequential processing, this order also defines the execution order.

        • viewPluginConfig: Configure your first ScanPlugin, similarly as you would for a single use case.

        • viewPluginConfig: Configure your second ScanPlugin, etc…​

    • cameraConfig: If omitted, default values will be selected…​

    • flashConfig: If omitted, default values will be selected…​

PluginResult Schema

Each of the configured ScanPlugins will return a PluginResult containing the corresponding result type. For example, a tinConfig will return a tinResult.

Below is a rough outline of the structure of a PluginResult:

  • PluginResult (returned for each configured PluginConfig)

    • Exactly one [xyz]Result (required): Returns a result corresponding to the ScanPlugin defined in ScanViewConfig → viewPluginConfig → pluginConfig → [xyz]Config. Examples: tinConfig → tinResult, barcodeConfig → barcodeResult, etc…​

    • pluginID (required): Corresponds to the ID defined in ScanViewConfig → viewPluginConfig → pluginConfig → id. Used to identify which ScanPlugin returned the result.

    • confidence (required): Informs about the general confidence of the digitized data.

    • cropRect: Provides information about the region that was processed within the image.

    • blobKey: Unique identifier of the scan result, its provision is license-dependent.

Resources Provided

  • Human-Readable Documentation: Based on the underlying JSON Schemas, we generated a clear, easy-to-follow documentation. This is your go-to reference for understanding each configuration option and result field.

  • Raw JSON Schema Files: These files are the source of truth and can be used for programmatic validation or integration with your development tools.

How to Use the Documentation

  1. Navigate: Use the table of contents or links within the human-readable documentation to find the specific configuration option or result field you’re interested in.

  2. Read Descriptions: Carefully review the descriptions provided. They’ll explain the purpose of each element, acceptable values, and any dependencies between fields.

  3. Check Types: Pay attention to the data types specified (e.g., string, number, boolean). These indicate what kind of values you should use when configuring scans.

  4. Example Usage: Check out our Developer Examples code on Github to see how configuration options or result fields might be used in practice.

Validating Your JSON

For a robust integration, consider using the raw JSON Schema files to validate your configuration JSON (ScanViewConfig) before sending it to the Mobile SDK. There are many JSON Schema validators available online or as libraries for various programming languages.

The SDK also provides a way to validate a JSON configuration object against the schema. On Android, this is done using the ScanViewConfigHolder class method validateJsonObject():

val validationResult = ScanViewConfigHolder.validateJsonObject(context, jsonObject)
when (validationResult) {
    is ScanViewConfigHolder.ScanViewJsonValidationResult.ValidationSucceeded ->
        assert(true) {
            "jsonObject contains a valid ScanViewConfig"
        }
    is ScanViewConfigHolder.ScanViewJsonValidationResult.ValidationFailed ->
        assert(false) {
            "jsonObject does not contain a valid ScanViewConfig: ${validationResult.exception.message}"
        }
}