UI Feedback Config

In many scenarios it could be useful to incorporate UI feedback elements to provide the user with real-time feedback about environment conditions detected during scanning, or content (i.e., format).

For instance:

  • You can display visual elements (such as images or text) next to the scan view’s cutout to more specifically guide the user on how or what to scan

  • You can cause sound files to play to prompt the user when certain conditions may lead to sub-optimal scanning (e.g. lighting too dark, sample too far)

  • You can configure visual elements to be "tappable", and allow these events to trigger code you may have prepared for this occasion (such as displaying an alert box with a message).

At this time, UI Feedback Config is only provided for use with internal presets.
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 provided a UI Feedback preset which includes a set of elements to improve the TIN scanning experience:

  • A customizable cutout guide image;

  • A customizable instruction label positioned above the cutout;

  • Configurable text, images and sound alerts for each user condition (brightness, distance and content)

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

TIN Preset usage sample

Below we have shown, through a sample config object in JSON, how our tin_custom_v1 preset can be defined. We would recommend that you take this JSON config provided as-is, and then adapt it as necessary.

TIN Preset Sample 
{
  "cameraConfig": {},
  "flashConfig": {},
  "viewPluginConfig": {
    "pluginConfig": {},
    "cutoutConfig": {},
    "scanFeedbackConfig": {},
    "uiFeedbackConfig": {
      "presets": [
        {
          "presetName": "tin_custom_v1",
          "presetAttributes": [
            {
              "attributeName": "lighting_toodark_image",
              "attributeValue": "ic_too_dark"
            },
            {
              "attributeName": "lighting_toobright_image",
              "attributeValue": "ic_too_bright"
            },
            {
              "attributeName": "distance_moveback_image",
              "attributeValue": "ic_move_back"
            },
            {
              "attributeName": "distance_movecloser_image",
              "attributeValue": "ic_move_closer"
            },
            {
              "attributeName": "format_wrong_image",
              "attributeValue": "ic_wrong_format"
            },
            {
              "attributeName": "date_wrong_image",
              "attributeValue": "ic_wrong_date"
            },
            {
              "attributeName": "lighting_toodark_text",
              "attributeValue": "Too dark"
            },
            {
              "attributeName": "lighting_toobright_text",
              "attributeValue": "Too bright"
            },
            {
              "attributeName": "distance_moveback_text",
              "attributeValue": "Position cutout correctly"
            },
            {
              "attributeName": "distance_movecloser_text",
              "attributeValue": "Position cutout correctly"
            },
            {
              "attributeName": "format_wrong_text",
              "attributeValue": "Wrong format detected"
            },
            {
              "attributeName": "date_wrong_text",
              "attributeValue": "Wrong date detected"
            },
            {
              "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 you can find the list of attributes included with the tin_custom_v1 preset, including their descriptions.

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.

With values for attributes that accept image or sound file assets, the runtime will attempt to locate them from within the main application bundle. For instance, the value provided to the format_wrong_image attribute needs to be identical to how it could have been accessed in the "normal" way, i.e.,

UIImage *imgForWrongFormat = [UIImage imageNamed:@"wrong_format_image"];
If an asset could not be found through the above method, the runtime will also attempt to load them from the SDK’s assets bundle before giving up and triggering a warning. Please refer to Tracing UI Feedback Config for additional information.
Sound files referenced in the config should be of the .wav file format.

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

ic_wrong_format

too bright icon

ic_too_bright

too dark icon

ic_too_dark

move back icon

ic_move_back

move closer icon

ic_move_closer

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

Tracing UI Feedback Config

In case you notice that the UI Feedback feature is not working correctly, or if some feedback is not being triggered as intended, the ALUIFeedbackLoggerDelegate can be helpful in order to trace logs (information, alerts and errors) made during the parsing of the UI Feedback configuration as well during the lifetime 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