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"
            }
          ]
        }
      ]
    }
  }
}

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.

TIN Preset Sample 
{
  "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

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
dot overlay

dot_overlay
wrong format icon

uifeedback_tin_wrongformat
too bright icon

uifeedback_tin_toobright
too dark icon

uifeedback_tin_toodark
move back icon

uifeedback_tin_moveback
move closer icon

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