UI Feedback Config

View this page on the iOS Documentation.

UI feedback elements can enhance the scanning experience, by informing the user about environmental conditions detected during scanning. Incorporating such elements during the scanning experience can be beneficial in many ways. For example:

Incorporating visual cues (such as images or text) next to the cutout within the scan view can guide the user on how or what to scan.
Using sound cues can alert the user when certain conditions are detected that might impact optimal scanning (e.g. insufficient lighting, incorrect distance from object, etc.).
Configuring interactive visual elements that trigger predefined actions, such as an alert message box, can offer users more options to improve their scanning practices.

At this time, UI Feedback Config is available for use with internal presets only.

Configuring a ScanViewConfig with the uiFeedbackConfig section

{
  "cameraConfig": {},
  "flashConfig": {},
  "viewPluginConfig": {
    "pluginConfig": {},
    "cutoutConfig": {},
    "scanFeedbackConfig": {},
    "uiFeedbackConfig": {
      "presets": [
        {
          "presetName": "internal_preset_name",
          "presetAttributes": [
            {
              "attributeName": "internal_preset_attribute1",
              "attributeValue": "value_of_attribute1"
            },
            {
              "attributeName": "internal_preset_attribute2",
              "attributeValue": "value_of_attribute2"
            }
          ]
        }
      ]
    }
  }
}

UI Feedback TIN preset

We have introduced a preconfigured UI Feedback preset designed to enhance the TIN scanning process, which includes:

A customizable cutout overlay guide image.
A customizable instruction label positioned above the cutout.
Configurable text, images, and sound alerts corresponding to various user conditions (such as brightness, distance, and content).

The UI Feedback TIN preset must be referred to by its name, tin_custom_v1.

TIN Preset usage sample

Below is a demonstration on how our tin_custom_v1 preset can be defined using a sample configuration object in JSON format. We suggest first utilizing this JSON configuration and making any necessary adaptations as needed.

{
  "cameraConfig": {},
  "flashConfig": {},
  "viewPluginConfig": {
    "pluginConfig": {},
    "cutoutConfig": {},
    "scanFeedbackConfig": {},
    "uiFeedbackConfig": {
      "presets": [
        {
          "presetName": "tin_custom_v1",
          "presetAttributes": [
            {
              "attributeName": "lighting_toodark_image",
              "attributeValue": "uifeedback_tin_toodark"
            },
            {
              "attributeName": "lighting_toobright_image",
              "attributeValue": "uifeedback_tin_toobright"
            },
            {
              "attributeName": "distance_moveback_image",
              "attributeValue": "uifeedback_tin_moveback"
            },
            {
              "attributeName": "distance_movecloser_image",
              "attributeValue": "uifeedback_tin_movecloser"
            },
            {
              "attributeName": "format_wrong_image",
              "attributeValue": "uifeedback_tin_wrongformat"
            },
            {
              "attributeName": "date_wrong_image",
              "attributeValue": "uifeedback_tin_wrongformat"
            },
            {
              "attributeName": "lighting_toodark_text",
              "attributeValue": ""
            },
            {
              "attributeName": "lighting_toobright_text",
              "attributeValue": ""
            },
            {
              "attributeName": "distance_moveback_text",
              "attributeValue": ""
            },
            {
              "attributeName": "distance_movecloser_text",
              "attributeValue": ""
            },
            {
              "attributeName": "format_wrong_text",
              "attributeValue": ""
            },
            {
              "attributeName": "date_wrong_text",
              "attributeValue": ""
            },
            {
              "attributeName": "lighting_toodark_sound",
              "attributeValue": "info_sound_TIN.wav"
            },
            {
              "attributeName": "lighting_toobright_sound",
              "attributeValue": "info_sound_TIN.wav"
            },
            {
              "attributeName": "distance_moveback_sound",
              "attributeValue": "info_sound_TIN.wav"
            },
            {
              "attributeName": "distance_movecloser_sound",
              "attributeValue": "info_sound_TIN.wav"
            },
            {
              "attributeName": "format_wrong_sound",
              "attributeValue": "info_sound_TIN.wav"
            },
            {
              "attributeName": "date_wrong_sound",
              "attributeValue": "info_sound_TIN.wav"
            }
          ]
        }
      ]
    }
  }
}

UI Feedback TIN preset attributes

Here is the list of attributes included with the tin_custom_v1 preset, including their descriptions.

While we do offer a DOT overlay, please note that it is specifically designed for TINs with the DOT prefix used in countries like the United States.

Name Type Description

Name	Type	Description
`lighting_toodark_image`	Image	Shown when the image is too dark to be processed. Used to advise the user to increase the lighting.
`lighting_toobright_image`	Image	Shown when there is too much light being received with the image. Used to advise the user to reduce the lighting.
`distance_moveback_image`	Image	Shown when the contours detected are outside the boundaries of the cutout. Used to advise the user to increase distance from scan target.
`distance_movecloser_image`	Image	Shown when the contours detected are too small. Can be used to prompt user to decrease distance from scan target.
`format_wrong_image`	Image	Shown when a result format is different from what is expected.
`date_wrong_image`	Image	Shown when a result format is different from what is expected.
`lighting_toodark_text`	String	Text shown when the image is too dark to be processed.
`lighting_toobright_text`	String	Text shown when too much light is being received with the image.
`distance_moveback_text`	String	Text shown when the contours detected are outside the boundaries of the cutout.
`distance_movecloser_text`	String	Text shown when the contours detected are too small.
`format_wrong_text`	String	Text shown when a result format is different from what is expected.
`date_wrong_text`	String	Text shown when a result format is different from what is expected.
`lighting_toodark_sound`	Sound file	Sound played when the image is too dark to be processed.
`lighting_toobright_sound`	Sound file	Sound played when too much light is being received with the image.
`distance_moveback_sound`	Sound file	Sound played when the contours detected are outside the boundaries of the cutout.
`distance_movecloser_sound`	Sound file	Sound played when the contours detected are too small.
`format_wrong_sound`	Sound file	Sound played when a result format is different from what is expected.
`date_wrong_sound`	Sound file	Sound played when a result format is different from what is expected.

lighting_toodark_image

Image

Shown when the image is too dark to be processed. Used to advise the user to increase the lighting.

lighting_toobright_image

Image

Shown when there is too much light being received with the image. Used to advise the user to reduce the lighting.

distance_moveback_image

Image

Shown when the contours detected are outside the boundaries of the cutout. Used to advise the user to increase distance from scan target.

distance_movecloser_image

Image

Shown when the contours detected are too small. Can be used to prompt user to decrease distance from scan target.

format_wrong_image

Image

Shown when a result format is different from what is expected.

date_wrong_image

Image

Shown when a result format is different from what is expected.

lighting_toodark_text

String

Text shown when the image is too dark to be processed.

lighting_toobright_text

String

Text shown when too much light is being received with the image.

distance_moveback_text

String

Text shown when the contours detected are outside the boundaries of the cutout.

distance_movecloser_text

String

Text shown when the contours detected are too small.

format_wrong_text

String

Text shown when a result format is different from what is expected.

date_wrong_text

String

Text shown when a result format is different from what is expected.

lighting_toodark_sound

Sound file

Sound played when the image is too dark to be processed.

lighting_toobright_sound

Sound file

Sound played when too much light is being received with the image.

distance_moveback_sound

Sound file

Sound played when the contours detected are outside the boundaries of the cutout.

distance_movecloser_sound

Sound file

Sound played when the contours detected are too small.

format_wrong_sound

Sound file

Sound played when a result format is different from what is expected.

date_wrong_sound

Sound file

Sound played when a result format is different from what is expected.

Attributes of type Image refer to a valid image resource identifier.
Attributes of type Sound file refer to .wav files inside the asset folder.

If at runtime these resources cannot be located in neither the app’s assets (sounds) and drawable resources (images) nor the SDK’s bundled assets (sounds) and drawable resources (images), the resources will not be used and a warning will be triggered, which can be inspected using Tracing UI Feedback Config.

Bundled Assets

The following image assets, also shown on the above sample JSON, are included with the SDK bundle and can be used with your app by referencing these names within the tin_custom_v1 preset:

Image Name

Image	Name
	`dot_overlay`
	`uifeedback_tin_wrongformat`
	`uifeedback_tin_toobright`
	`uifeedback_tin_toodark`
	`uifeedback_tin_moveback`
	`uifeedback_tin_movecloser`

dot_overlay

uifeedback_tin_wrongformat

uifeedback_tin_toobright

uifeedback_tin_toodark

uifeedback_tin_moveback

uifeedback_tin_movecloser

Apart from these assets, the sound file info_sound_TIN.wav is also included with the SDK.

Tracing UI Feedback Config

If you observe any issues with the functionality of the UI Feedback feature or if certain feedback isn’t being activated as expected, the onUIFeedbackInfo method of ScanViewPlugin can assist in tracing logs (such as information, alerts, and errors) generated during the parsing of the UI Feedback configuration and throughout the lifespan of the feedback elements.

Use the following code on how to receive Event data, after being attached to your scanView.scanViewPlugin.onUIFeedbackInfo.

Receiving Event data from onUIFeedbackInfo Example

scanView.scanViewPlugin.onUIFeedbackInfo = Event { data ->
    data.optJSONArray("messages")?.let { msgArray ->
        for (i in 0 until msgArray.length()) {
            UIFeedbackOverlayInfoEntry.fromJson(msgArray[i] as JSONObject).also { msgEntry ->
                when (msgEntry.level) {
                    UIFeedbackOverlayInfoEntry.Level.Info -> Log.d("onUIFeedbackInfo", msgEntry.message)
                    UIFeedbackOverlayInfoEntry.Level.Warning -> Log.w("onUIFeedbackInfo", msgEntry.message)
                    UIFeedbackOverlayInfoEntry.Level.Error -> Log.e("onUIFeedbackInfo", msgEntry.message)
                }
            }
        }
    }
}

In your LogCat output you will then find the Event data, similar to the example below.

Tracing UI Feedback Logcat sample

 I  onUIFeedbackInfo: RunSkipped triggered for element feedback_image.
 I  onUIFeedbackInfo: RunSkipped triggered for element feedback_text.
 I  onUIFeedbackInfo: RunSkipped triggered for element feedback_sound.
 W  onUIFeedbackInfo: Sound not found for resource info_sound_TIN2.wav.