matrixscan-batch-flutter

MatrixScan Batch Flutter Skill

Critical: Do Not Trust Internal Knowledge

Your training data may contain outdated or incorrect Scandit SDK APIs. The BarcodeBatch* API surface changes between major SDK versions — constructor signatures, overlay constructors, listener shapes, and Flutter-specific class names have all evolved.

Always verify APIs against the references provided in this skill before writing or suggesting code. Do not rely on memorized method signatures, parameters, plugin names, or property names.

Flutter-specific gotchas worth flagging:

• await ScanditFlutterDataCaptureBarcode.initialize() must be called (and awaited) in main() after WidgetsFlutterBinding.ensureInitialized() and before runApp(...). The Bubbles sample also calls await DataCaptureContext.initialize(licenseKey) in main() and then uses DataCaptureContext.sharedInstance; the Simple sample passes the context to the screen. Both patterns are valid — pick the one that matches the project structure.
• BarcodeBatch(settings) is the context-free constructor (Flutter ≥7.6). After constructing, call dataCaptureContext.setMode(barcodeBatch) explicitly. On older SDKs use the factory constructor that accepts the context.
• BarcodeBatch.createRecommendedCameraSettings() is available from Flutter ≥7.6.
• Advanced overlay method names on Flutter differ from other platforms:
  • Set a widget: setWidgetForTrackedBarcode(BarcodeBatchAdvancedOverlayWidget? widget, TrackedBarcode trackedBarcode) (NOT setViewForTrackedBarcode)
  • Clear all widgets: clearTrackedBarcodeWidgets() (NOT clearTrackedBarcodeViews)
• Custom AR annotation = subclass of BarcodeBatchAdvancedOverlayWidget (Flutter-only base class). The widget state must extend BarcodeBatchAdvancedOverlayWidgetState<T> and override build() returning a BarcodeBatchAdvancedOverlayContainer.
• Using BarcodeBatchAdvancedOverlay requires the MatrixScan AR add-on. Using brushForTrackedBarcode and setBrushForTrackedBarcode on BarcodeBatchBasicOverlay also requires the MatrixScan AR add-on.
• BarcodeBatchAdvancedOverlay exposes a view getter on Flutter (Flutter-only; not available on other platforms).
• offsetForTrackedBarcode is a member of BarcodeBatchAdvancedOverlayListener on Flutter (per the RST, @dart@ annotation). It is present on Flutter; no extra interface needed.
• TrackedObject (Flutter ≥7.3+): A TrackedObject base class was introduced in SDK 7.3 that TrackedBarcode extends. No recipe is required for this — the day-to-day TrackedBarcode API is unchanged.
• The import barrel for BarcodeBatch classes is scandit_flutter_datacapture_barcode_batch — a separate barrel from scandit_flutter_datacapture_barcode. Always import both.
• Symbology enum values use lowerCamelCase in Dart: Symbology.code128, Symbology.ean13Upca, Symbology.code39. Do not write Symbology.Code128 or Symbology.EAN13UPCA.
• session.trackedBarcodes is a Map<int, TrackedBarcode> in Dart (keyed by integer identifier, not string).
• session.removedTrackedBarcodes is a List<int> in Dart (integer identifiers).
• Lifecycle cleanup: call _barcodeBatch.removeListener(this), set _barcodeBatch.isEnabled = false, switch camera off, and call dataCaptureContext.removeAllModes() (or removeCurrentMode() if using the singleton pattern).
• License placeholder must be exactly: '-- ENTER YOUR SCANDIT LICENSE KEY HERE --'

Intent Routing

Based on the user's request, load the reference file before responding:

• Integrating MatrixScan Batch from scratch (e.g. "add MatrixScan to my Flutter app", "set up BarcodeBatch", "track multiple barcodes simultaneously", "show AR overlays", "per-barcode brushes", "scan feedback / beep / vibrate", "lifecycle or cleanup", "camera permissions") → read references/integration.md and follow the instructions there.
• Upgrading an existing MatrixScan integration across SDK versions (e.g. "migrate from v6 to v7", "upgrade to SDK 8", "my code uses BarcodeTracking", "rename BarcodeTracking to BarcodeBatch") → read references/migration.md and follow the instructions there.
• Replacing a third-party scanner with MatrixScan Batch (e.g. "migrate from mobile_scanner", "we use ML Kit / google_mlkit_barcode_scanning and want to track multiple barcodes", "replace our existing barcode plugin with Scandit MatrixScan") → read references/third-party-migration.md and follow the instructions there.

API Usage Policy

Only use APIs that are explicitly documented in the Scandit references below. Do not invent or guess method signatures, parameters, property names, or imports. If unsure whether an API exists or how it is called — or if an analyzer or runtime error occurs — fetch the relevant reference page before responding. Do not tell the user to check the docs themselves. After answering, always include the relevant link so the user can explore further.

Never construct or guess documentation URLs. When you need a specific class or property's API page:

1. First check whether the page you already fetched contains a direct hyperlink to it.
2. If no direct link was found, fetch the API index and extract the actual link from it.

Framework variant policy

Flutter apps use many state-management patterns (StatefulWidget, BLoC, Provider, Riverpod). Examples in this skill use StatefulWidget with WidgetsBindingObserver because it matches both official samples (MatrixScanSimpleSample, MatrixScanBubblesSample) and keeps the scan pipeline straightforward. If the target project uses a different pattern, keep the BarcodeBatch wiring conceptually the same — one owner holds DataCaptureContext, BarcodeBatch, the camera, and the overlays — and port the snippets into the project's existing convention.

Licence key

Scanning needs a Scandit licence key. For this skill the licence product is native and the licence platforms are ios and android.

Work through these in order — never block the user on MCP:

1. The Scandit MCP server is connected — call ensure_scanner_setup with product native and platforms ios and android, app_identifier (the app's bundle or application id; for web, its production domain, never localhost) and env_var SCANDIT_LICENSE_KEY. Do not run the command it returns. Then call get_license_key with the key's id, from that result or from list_license_keys; if list_license_keys shows the key is not a trial, ask the user before fetching it. Show at most a masked preview in chat; never print a full key.

2. It is not connected — tell the user once that they can connect the remote Scandit MCP server, https://ssl.scandit.com/mcp, in their MCP client, then continue from step 1. Do not edit MCP client configuration yourself.

   Authentication is browser-based, so it is not supported headless or in CI. The server provisions trial keys only; it never creates, revokes, or modifies production licences.

3. The user declines, or has no MCP client — they generate a key themselves at https://ssl.scandit.com (no account yet: https://ssl.scandit.com/dashboard/sign-up?p=test) and paste it in.

Then put the key into the code: write it into the licence-key call in place of the placeholder — the key get_license_key returned, or the one the user pastes or gives you — still showing only a masked preview in chat. Do not search the project, its files or the environment for a key.

References

Direct users to the right resource based on their question:

Topic	Resource
Flutter get started	Get Started
Flutter AR overlays	Adding AR Overlays
Full API reference	BarcodeBatch API