UI Feedback Config

View this page on the Android 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"
            }
          ]
        }
      ]
    }
  }
}

Simple Instruction Label preset

This is a simple UI Feedback preset which adds a customizable instruction label positioned above the cutout.

The Simple Instruction Label preset must be referred to by its name, simple_instruction_label.

Simple Instruction Label preset usage sample

Below is a demonstration on how our simple_instruction_label preset can be defined using a sample configuration object in JSON format.

{
  "cameraConfig": {},
  "flashConfig": {},
  "viewPluginConfig": {
    "pluginConfig": {},
    "cutoutConfig": {},
    "scanFeedbackConfig": {},
    "uiFeedbackConfig": {
      "presets": [
        {
          "presetName": "simple_instruction_label",
          "presetAttributes": [
            {
              "attributeName": "instruction_text",
              "attributeValue": "Please scan License Plate"
            }
          ]
        }
      ]
    }
  }
}

Simple Instruction Label preset attributes

Name

Type

Description

instruction_text

String

Text shown above the cutout.

Cutout Bottom Image Element preset

This is a simple UI Feedback preset which adds a customizable image positioned bellow the cutout. The image provided will be scaled in a way that its width will fit the cutout width and its height will be scaled according with the original aspect of the image.

The Cutout Bottom Image Element preset must be referred to by its name, cutout_bottom_image_element.

Cutout Bottom Image Element preset usage sample

Below is a demonstration on how our cutout_bottom_image_element preset can be defined using a sample configuration object in JSON format.

Cutout Bottom Image Element preset Sample

{
  "cameraConfig": {},
  "flashConfig": {},
  "viewPluginConfig": {
    "pluginConfig": {},
    "cutoutConfig": {},
    "scanFeedbackConfig": {},
    "uiFeedbackConfig": {
      "elements": [
        {
          "presets": [
            {
              "presetName": "cutout_bottom_image_element",
              "presetAttributes": [
                {
                  "attributeName": "image",
                  "attributeValue": "cutout_bottom_image_element_sample"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Cutout Bottom Image Element preset attributes

Name

Type

Description

image

Image

Shown bellow the cutout, bounded with the cutout width and scaled by height preserving the original aspect ratio.

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

For additional implementation guidance, please review our Knowledge Base Article.

TIN Preset usage sample

Below is a demonstration on how our tin_with_instruction_overlay_image_text_sound_feedback 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_with_instruction_overlay_image_text_sound_feedback",
          "presetAttributes": [
            {
              "attributeName": "instruction_text",
              "attributeValue": "Please make sure the entire DOT number is inside the cutout."
            },
            {
              "attributeName": "left_overlay_image",
              "attributeValue": "dot_overlay"
            },
            {
              "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_with_instruction_overlay_image_text_sound_feedback 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

instruction_text

String

Shown above the cutout.

left_overlay_image

Image

Shown inside the cutout, aligned to the left.

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.

Both attributes of type Image and Sound refer to assets in the main application bundle or SDK’s bundled assets.
Sound files need to be of the .wav file format.

If at runtime these assets cannot be located in neither the application bundle nor the SDK bundled assets, the asset will not be used and a warning will be triggered, which can be inspected using Tracing UI Feedback Config.

For instance, the value provided to the wrong_format_image attribute needs to be identical to how it would have been accessed using Objective-C code:

UIImage *imgForWrongFormat = [UIImage imageNamed:@"wrong_format_image"];

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

Setting up UI Feedback logging using ALUIFeedbackLogger

#import <Anyline/Anyline.h>

- (void)viewDidLoad {
    ...
    // Set this delegate before the UI Feedback config is parsed in order
    // to not miss any related logs
    [ALUIFeedbackLogger sharedInstance].delegate = self;
}

- (void)loggedUIFeedbackMessage:(NSString *)message level:(enum ALUIFeedbackLogLevel)level {
    NSString *prefix = @"";
    switch (level) {
        case ALUIFeedbackLogLevelInfo: prefix = @"I"; break;
        case ALUIFeedbackLogLevelWarn: prefix = @"W"; break;
        case ALUIFeedbackLogLevelError: prefix = @"E"; break;
        default: break;
    }
    NSLog(@"%@ %@", prefix, message);
}

On your Xcode console window you will then find logs similar to the following:

Tracing UI Feedback console sample

I 1710159907.394311 - parsing UIFeedbackConfig from JSON
I 1710159907.398178 - expanding presets for UIFeedbackConfig
I 1710159907.406073 - expanding element overlay presets for element instruction_text
I 1710159907.4062681 - expanding element overlay presets for element dot_image
I 1710159907.4063659 - expanding element overlay presets for element feedback_image
I 1710159907.406435 - expanding element trigger presets for element feedback_image
I 1710159907.406512 - expanding element overlay presets for element feedback_text
I 1710159907.406568 - expanding element trigger presets for element feedback_text
I 1710159907.406633 - expanding element trigger presets for element feedback_sound
I 1710159907.406775 - UIFeedbackConfig object successfully created
I 1710159907.6487 - adding feedback element: instruction_text
I 1710159907.652498 - adding feedback element: dot_image
I 1710159907.653325 - adding feedback element: feedback_image
I 1710159907.65344 - adding feedback element: feedback_text
I 1710159907.654182 - adding feedback element: feedback_sound
I 1710159908.328483 - ScanInfo triggered for element image_feedback_image
I 1710159908.328576 - ScanInfo triggered for element text_feedback_text
I 1710159908.328617 - ScanInfo triggered for element sound_feedback_sound