Advanced Configurations

Customization of the Overlays

Basic Overlay

To customize the appearance of an overlay you can implement a ILabelCaptureBasicOverlayListener and/or ILabelCaptureAdvancedOverlayListener interface, depending on the overlay(s) you are using.

The method BrushForLabel() is called every time a label is captured, and BrushForField() is called for each of its fields to determine the brush for the label or field.

public class BasicOverlayListener : Java.Lang.Object, ILabelCaptureBasicOverlayListener
{
    private readonly Context context;

    public BasicOverlayListener(Context context)
    {
        this.context = context;
    }

    /*
     * Customize the appearance of the overlay for the individual fields.
     */
    public Brush? BrushForField(
        LabelCaptureBasicOverlay overlay,
        LabelField field,
        CapturedLabel label)
    {
        return field.Name switch
        {
            "<your-barcode-field-name>" => new Brush(
                fillColor: new Color(context.GetColor(Resource.Color.barcode_highlight)),
                strokeColor: new Color(context.GetColor(Resource.Color.barcode_highlight)),
                strokeWidth: 1f
            ),
            "<your-expiry-date-field-name>" => new Brush(
                fillColor: new Color(context.GetColor(Resource.Color.expiry_date_highlight)),
                strokeColor: new Color(context.GetColor(Resource.Color.expiry_date_highlight)),
                strokeWidth: 1f
            ),
            _ => null
        };
    }

    /*
     * Customize the appearance of the overlay for the full label.
     * In this example, we disable label overlays by returning null always.
     */
    public Brush? BrushForLabel(
        LabelCaptureBasicOverlay overlay,
        CapturedLabel label)
    {
        return null;
    }

    public void OnLabelTapped(
        LabelCaptureBasicOverlay overlay,
        CapturedLabel label)
    {
        /*
         * Handle the user tap gesture on the label.
         */
    }
}

// Set the listener on the overlay
overlay.Listener = new BasicOverlayListener(context);

tip

You can also use LabelCaptureBasicOverlay.LabelBrush, LabelCaptureBasicOverlay.CapturedFieldBrush, and LabelCaptureBasicOverlay.PredictedFieldBrush properties to configure the overlay if you don't need to customize the appearance based on the name or content of the fields.

Advanced Overlay

For more advanced use cases, such as adding custom views or implementing Augmented Reality (AR) features, you can use the LabelCaptureAdvancedOverlay. The example below creates an advanced overlay, configuring it to display a styled warning message below expiry date fields when they're close to expiring, while ignoring other fields.

// Create an advanced overlay that allows for custom views to be added over detected label fields
// This is the key component for implementing Augmented Reality features
var advancedOverlay = LabelCaptureAdvancedOverlay.Create(labelCapture);

// Add the overlay to the data capture view
dataCaptureView.AddOverlay(advancedOverlay);

// Configure the advanced overlay with a listener that handles AR content creation and positioning
advancedOverlay.Listener = new AdvancedOverlayListener(this);

public class AdvancedOverlayListener : Java.Lang.Object, ILabelCaptureAdvancedOverlayListener
{
    private readonly Context context;

    public AdvancedOverlayListener(Context context)
    {
        this.context = context;
    }

    // This method is called when a label is detected - we return null since we're only adding AR elements to specific fields, not the entire label
    public View? ViewForCapturedLabel(
        LabelCaptureAdvancedOverlay overlay,
        CapturedLabel capturedLabel)
    {
        return null;
    }

    // This defines where on the detected label the AR view would be anchored
    public Anchor AnchorForCapturedLabel(
        LabelCaptureAdvancedOverlay overlay,
        CapturedLabel capturedLabel)
    {
        return Anchor.Center;
    }

    // This defines the offset from the anchor point for the label's AR view
    public PointWithUnit OffsetForCapturedLabel(
        LabelCaptureAdvancedOverlay overlay,
        CapturedLabel capturedLabel,
        View view)
    {
        return new PointWithUnit(0f, 0f, MeasureUnit.Pixel);
    }

    // This method is called when a field is detected in a label
    public View? ViewForCapturedLabelField(
        LabelCaptureAdvancedOverlay overlay,
        LabelField labelField)
    {
        // We only want to create AR elements for expiry date fields that are text-based
        if (labelField.Name.ToLower().Contains("expiry") && labelField.Type == LabelFieldType.Text)
        {
            //
            // data extraction from expiry date field and days until expiry date calculation
            //

            // Check if scanned expiry date is too close to actual date
            var daysUntilExpiry = CalculateDaysUntilExpiry(labelField.Text);
            var dayLimit = 3;

            if (daysUntilExpiry < dayLimit)
            {
                // Create and configure the AR element - a TextView with appropriate styling
                // This view will appear as an overlay on the camera feed
                var textView = new TextView(context)
                {
                    Text = "Item expires soon!",
                    TextSize = 14f
                };
                textView.SetTextColor(Android.Graphics.Color.White);
                textView.SetBackgroundColor(Android.Graphics.Color.Red);
                textView.SetPadding(16, 8, 16, 8);

                // Add an icon to the left of the text for visual guidance
                // This enhances the AR experience by providing clear visual cues
                var drawable = ContextCompat.GetDrawable(context, Resource.Drawable.ic_warning);
                if (drawable != null)
                {
                    drawable.SetBounds(0, 0, drawable.IntrinsicWidth, drawable.IntrinsicHeight);
                    textView.SetCompoundDrawables(drawable, null, null, null);
                }
                textView.CompoundDrawablePadding = 16; // Add some padding between icon and text

                return textView;
            }
        }
        // Return null for any fields that aren't expiry dates, which means no AR overlay
        return null;
    }

    // This defines where on the detected field the AR view should be anchored
    // BottomCenter places it right below the expiry date text for better visibility
    public Anchor AnchorForCapturedLabelField(
        LabelCaptureAdvancedOverlay overlay,
        LabelField labelField)
    {
        return Anchor.BottomCenter;
    }

    // This defines the offset from the anchor point
    public PointWithUnit OffsetForCapturedLabelField(
        LabelCaptureAdvancedOverlay overlay,
        LabelField labelField,
        View view)
    {
        return new PointWithUnit(0f, 22f, MeasureUnit.Dip);
    }

    private int CalculateDaysUntilExpiry(string? expiryDateText)
    {
        // Parse the expiry date and calculate days remaining
        // Implementation depends on your date format
        return 0; // placeholder
    }
}

Validation Flow

How It Works

The Validation Flow provides a guided label scanning experience. An always-present checklist shows users exactly which fields have been captured and which are still missing, making the scanning process transparent and efficient. Scanning is the fastest way to capture all label content — whether all fields are visible at once or spread across different sides of a package.

The fields shown in the checklist are driven by your Label Definition — the configuration that tells Label Capture which fields to recognize and extract. See the Label Definitions guide for details on how to set them up.

The Validation Flow overlay is a UI component built on top of Label Capture. To use it, create a LabelCaptureValidationFlowOverlay and add it to your data capture view.

Single-Step Scan	Multi-Step Scan
All fields are visible together	Fields on different sides of the package

// Create the validation flow overlay with the label capture mode and data capture view
var validationFlowOverlay = LabelCaptureValidationFlowOverlay.Create(labelCapture, dataCaptureView);

// Set the listener to receive validation events
validationFlowOverlay.Listener = new ValidationFlowListener();

Define a Listener

When the user has verified that all fields are correctly captured and presses the finish button, the Validation Flow triggers a callback with the final results. To receive these results, implement the ILabelCaptureValidationFlowListener interface:

public class ValidationFlowListener : Java.Lang.Object, ILabelCaptureValidationFlowListener
{
    // This is called by the validation flow overlay when a label has been fully captured and validated
    public void OnValidationFlowLabelCaptured(IList<LabelField> fields)
    {
        string? barcodeData = null;
        string? expiryDate = null;

        foreach (var field in fields)
        {
            if (field.Name == "<your-barcode-field-name>")
            {
                barcodeData = field.Barcode?.Data;
            }
            else if (field.Name == "<your-expiry-date-field-name>")
            {
                expiryDate = field.Text;
            }
        }

        // Process the captured and validated data
    }
}

Required and Optional Fields

The Validation Flow clearly indicates which fields must be captured and which are optional. Required fields are visually highlighted and the flow can only be completed once all of them have been successfully scanned or manually entered. Optional fields are shown but do not block the user from finishing.

Required Field	Optional Field
Must be captured to finish the flow	Does not block finishing

Typing Hints

If neither on-device nor cloud-based scanning can capture a field, the user can always manually enter the value. To make manual input easier and reduce errors, you can configure placeholder text (typing hints) that show the expected format directly in the input field.

The field name in the label definition is used as the reference for setting placeholder text:

var validationFlowOverlaySettings = LabelCaptureValidationFlowSettings.Create();
validationFlowOverlaySettings.SetPlaceholderText("MM/DD/YYYY", "Expiry Date");

validationFlowOverlay.ApplySettings(validationFlowOverlaySettings);

Customization

All text in the Validation Flow overlay can be adjusted to match your application's needs. This is useful for localization, adapting terminology, or removing text entirely for a minimal interface.

Buttons

The text on the restart, pause, and finish buttons can be customized or removed entirely.

English (Default)	Custom Language	Company Slang	No Text

var validationFlowOverlaySettings = LabelCaptureValidationFlowSettings.Create();
validationFlowOverlaySettings.RestartButtonText = "Borrar todo";
validationFlowOverlaySettings.PauseButtonText = "Pausar";
validationFlowOverlaySettings.FinishButtonText = "Finalizar";

validationFlowOverlay.ApplySettings(validationFlowOverlaySettings);

Toasts

Toast messages appear at the top of the camera preview to inform the user about a scanning state change. The standby toast is shown when the camera is auto-paused after no label is detected for a long time. The validation toast shows how many fields have been captured so far after a scan.

Standby	Validation

var validationFlowOverlaySettings = LabelCaptureValidationFlowSettings.Create();
validationFlowOverlaySettings.StandbyHintText = "No label detected, camera paused";
validationFlowOverlaySettings.ValidationHintText = "data fields collected"; // X/Y (X fields out of total Y) is shown in front of this string

validationFlowOverlay.ApplySettings(validationFlowOverlaySettings);

Field

The field state texts are shown inside the input field itself during different phases of scanning.

Invalid Input	Scanning Text	Adaptive Scanning Text
Shown when manual input does not match the expected format	Shown while the camera is actively scanning	Shown while cloud-based recognition is processing

var validationFlowOverlaySettings = LabelCaptureValidationFlowSettings.Create();
validationFlowOverlaySettings.ValidationErrorText = "Incorrect format.";
validationFlowOverlaySettings.ScanningText = "Scan in progress";
validationFlowOverlaySettings.AdaptiveScanningText = "Processing";

validationFlowOverlay.ApplySettings(validationFlowOverlaySettings);

Cloud Fallback

Beta

The Adaptive Recognition API is still in beta and may change in future versions of Scandit Data Capture SDK. To enable it on your subscription, please contact support@scandit.com.

The Adaptive Recognition Engine helps making Smart Label Capture more robust and scalable thanks to its larger, more capable model hosted in the cloud. Whenever Smart Label Capture's on-device model fails to capture data, the SDK will automatically trigger the Adaptive Recognition Engine to capture complex, unforeseen data and process it with high accuracy and reliability — avoiding the need for the user to type data manually.

Enable Adaptive Recognition by setting the mode to .auto on the label definition. This is a single extra line added to your existing label definition configuration:

private LabelCaptureSettings BuildLabelCaptureSettings()
{
    var fields = new List<LabelFieldDefinition>();

    var customBarcode = CustomBarcode.Builder()
        .SetSymbologies(new List<Symbology>
        {
            Symbology.Ean13Upca,
            Symbology.Gs1DatabarExpanded,
            Symbology.Code128
        })
        .Build(FIELD_BARCODE);
    fields.Add(customBarcode);

    var expiryDateText = ExpiryDateText.Builder()
        .SetLabelDateFormat(new LabelDateFormat(LabelDateComponentFormat.MDY, acceptPartialDates: false))
        .Build(FIELD_EXPIRY_DATE);
    fields.Add(expiryDateText);

    var labelDefinition = LabelDefinition.Create(LABEL_RETAIL_ITEM, fields);
    labelDefinition.AdaptiveRecognitionMode = AdaptiveRecognitionMode.Auto;

    var settings = LabelCaptureSettings.Create(new List<LabelDefinition> { labelDefinition });
    return settings;
}

See AdaptiveRecognitionMode for available options.