Scan shipping labels

Shipping Label Scanning reads a shipping label and returns its tracking ID, the receiver's name and address, and the carrier. Like receipt scanning, it uses the Adaptive Recognition Engine, which processes the label in the cloud.

To read your own set of fields on the device instead, define a custom label.

Beta

Shipping Label Scanning requires the Adaptive Recognition Engine, which is still in beta and may change in future versions of Scandit Data Capture SDK. To enable it on your subscription, contact support@scandit.com.

Before you start

• Use Scandit Data Capture SDK 8.6.0 or later. Shipping Label Scanning is available on iOS, Android, and Web. It isn't available on other frameworks yet.
• Ask support@scandit.com to enable the Adaptive Recognition Engine on your subscription.
• Make sure the device has a network connection. The Adaptive Recognition Engine processes the label in the cloud.
• Set up a LabelCapture instance and a DataCaptureView. If you haven't done this yet, follow Get started.

Create the LabelCapture instance with LabelCaptureSettings that have no label definitions. The overlay adds its own definition for the tracking barcode. Label definitions that you add stay active alongside it, so a barcode that isn't the tracking barcode can end up as the trackingId.

import com.scandit.datacapture.label.capture.LabelCapture
import com.scandit.datacapture.label.capture.LabelCaptureSettings

val labelCaptureSettings = LabelCaptureSettings.builder().build()
val labelCapture = LabelCapture.forDataCaptureContext(dataCaptureContext, labelCaptureSettings)

Steps

1. Create the settings

Create LabelCaptureAdaptiveRecognitionSettings with the result type AdaptiveRecognitionResultType.SHIPPING_LABEL. The result type sets the kind of document that the overlay looks for.

To change the hint that the overlay shows while it processes a label, use processingHintText.

import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.AdaptiveRecognitionResult
import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.AdaptiveRecognitionResultType
import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.LabelCaptureAdaptiveRecognitionListener
import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.LabelCaptureAdaptiveRecognitionOverlay
import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.LabelCaptureAdaptiveRecognitionSettings
import com.scandit.datacapture.label.ui.overlay.adaptiverecognition.ShippingLabelScanningResult

val settings = LabelCaptureAdaptiveRecognitionSettings.newInstance(
    AdaptiveRecognitionResultType.SHIPPING_LABEL
)

2. Create the overlay

Create the overlay with LabelCaptureAdaptiveRecognitionOverlay.newInstance(context, mode, view). Then apply the settings with applySettings(settings).

When you pass your DataCaptureView, the overlay adds itself to the view. If you pass null instead, add the overlay yourself with DataCaptureView.addOverlay().

Keep the overlay in a property of your Activity or Fragment, and create it when the view is created, for example in a Fragment's onViewCreated method. Then forward the lifecycle to the overlay. Call onResume() in your onResume method to start or restore scanning. Call onPause() in your onPause method to pause it.

private lateinit var overlay: LabelCaptureAdaptiveRecognitionOverlay

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    overlay = LabelCaptureAdaptiveRecognitionOverlay.newInstance(
        requireContext(),
        labelCapture,
        dataCaptureView,
    )
    overlay.applySettings(settings)
}

override fun onResume() {
    super.onResume()
    overlay.onResume()
}

override fun onPause() {
    overlay.onPause()
    super.onPause()
}

3. Listen for results

Set a LabelCaptureAdaptiveRecognitionListener as the overlay's listener. It receives two callbacks:

• onRecognized(result) runs when the label is recognized. Check that the result is a ShippingLabelScanningResult, then read its fields.
• onFailure() runs when recognition fails, for example because of a connection error.

overlay.listener = object : LabelCaptureAdaptiveRecognitionListener {
    override fun onRecognized(result: AdaptiveRecognitionResult) {
        val shippingLabel = result as? ShippingLabelScanningResult ?: return

        val trackingId = shippingLabel.trackingId
        val receiverName = shippingLabel.receiverFullName
        val receiverCompany = shippingLabel.receiverCompany // null if the label doesn't show one
        val carrier = shippingLabel.carrier
    }

    override fun onFailure() {
        // Recognition failed, for example because of a connection error.
    }
}

4. Switch the camera back on

When the overlay starts to process a label, it switches the camera to standby. It doesn't switch the camera back on after a result. To scan the next label, call the camera's switchToDesiredState(FrameSourceState.ON) in onRecognized(result) after you handle the result.

The overlay doesn't switch the camera back on after a failure either. Call switchToDesiredState(FrameSourceState.ON) in onFailure() too, so that you can scan the label again.

override fun onRecognized(result: AdaptiveRecognitionResult) {
    // Handle the result, then get ready for the next label.
    camera.switchToDesiredState(FrameSourceState.ON)
}

override fun onFailure() {
    // Get ready to scan the label again.
    camera.switchToDesiredState(FrameSourceState.ON)
}

Shipping label fields

ShippingLabelScanningResult has the following fields:

Field	Type	Description
trackingId	String	The tracking identifier, read from the tracking barcode on the label.
receiverFullName	String	The receiver's full name.
receiverCompany	String?	The receiver's company. null if the label doesn't show one.
receiverStreet	String	The street of the receiver's address.
receiverCity	String	The city of the receiver's address.
receiverState	String?	The state of the receiver's address. null if the label doesn't show one.
receiverPostalCode	String	The postal code of the receiver's address.
receiverCountry	String?	The country of the receiver's address. null if the label doesn't show one.
carrier	Carrier	The postal provider of the label. See Carriers.

Handle missing values

• receiverCompany, receiverState, and receiverCountry are null when the label doesn't show them. Check for null before you use them.
• carrier is Carrier.NOT_AVAILABLE when no carrier is identified on the label, or when the identified carrier isn't in the list below. It's Carrier.OTHER only when the engine classifies the carrier as other.

Carriers

Carrier has the following values. The SDK maps the carrier that the engine identifies on the label to one of these values. The list can grow in future SDK versions.

Carrier	Value
FedEx	Carrier.FEDEX
United Parcel Service (UPS)	Carrier.UPS
United States Postal Service (USPS)	Carrier.USPS
DHL	Carrier.DHL
DPD	Carrier.DPD
GLS	Carrier.GLS
TNT	Carrier.TNT
Amazon Logistics	Carrier.AMAZON_LOGISTICS
OnTrac	Carrier.ONTRAC
Royal Mail	Carrier.ROYAL_MAIL
Parcelforce	Carrier.PARCELFORCE
Evri	Carrier.EVRI
Yodel	Carrier.YODEL
Chronopost	Carrier.CHRONOPOST
Colissimo	Carrier.COLISSIMO
Mondial Relay	Carrier.MONDIAL_RELAY
Poste Italiane	Carrier.POSTE_ITALIANE
BRT	Carrier.BRT
SDA	Carrier.SDA
Hermes	Carrier.HERMES
Austrian Post	Carrier.AUSTRIAN_POST
Swiss Post	Carrier.SWISS_POST
PostNL	Carrier.POSTNL
bpost	Carrier.BPOST
PostNord	Carrier.POSTNORD
Correos	Carrier.CORREOS
SEUR	Carrier.SEUR
InPost	Carrier.INPOST
Classified by the engine as other	Carrier.OTHER
Not identified, or not in this list	Carrier.NOT_AVAILABLE

Verify it works

You're done when:

• The overlay shows its processing hint after you point the camera at a shipping label.
• Your onRecognized(result) callback receives a ShippingLabelScanningResult, and you can read its trackingId and carrier.
• Your onRecognized(result) code switches the camera back on after each result, so you can scan the next label.

• Your onFailure() code also switches the camera back on, so you can scan the label again.

Processing starts only after the SDK decodes a tracking barcode on the label. The tracking barcode must be Code 128, Code 39, ITF, Data Matrix, or PDF417. Processing also requires a license key that includes Adaptive Recognition. If the overlay never shows its processing hint, check that the label has one of these barcodes and that your license key includes Adaptive Recognition.

If onFailure() runs instead, recognition failed, for example because of a network problem or a label the engine can't read. Check the network connection, then scan the label again.

Related

• Advanced configurations, including Receipt Scanning and Cloud Fallback
• Label definitions
• API reference: ShippingLabelScanningResult, Carrier, LabelCaptureAdaptiveRecognitionSettings, LabelCaptureAdaptiveRecognitionOverlay, LabelCaptureAdaptiveRecognitionListener