Scan Result Handling

This page explains the structure of scan results, how to access result data and images, and best practices for result handling.

Result Structure

The SDK delivers scan results as WrapperSessionScanResultsResponse objects through the onScanResults event stream. Each response contains an array of ExportedScanResult objects, the structured representation of what the scanner detected, including the recognized data, confidence score, and optionally captured images.

Top-Level Fields

Field Type Description

exportedScanResults

List

Array of ExportedScanResult objects, one per detected item

scanResultConfig

Object

The result configuration that was active during scanning

scanResultExtraInfo

Object

Additional metadata about the scan results

ExportedScanResult Fields

Each ExportedScanResult in the exportedScanResults array contains:

Field Type Description

pluginResult

Object

The plugin-specific scan result (contains pluginID, confidence, and result data per plugin type)

imageContainer

Object

Image delivery container with encoded (Base64) and/or saved (file paths) sub-objects

imageParameters

Object

Image format and quality settings used for export

The pluginResult structure varies by plugin type. See PluginResult Documentation for the full schema definition.

Receiving Results

Subscribe to the onScanResults event stream to receive results. The listener below demonstrates iterating over results and handling images:

  • Flutter

final subscription = infinityPlugin.onScanResults.listen((result) {
  // Iterate over all results in this batch (may contain multiple when using composite scanning)
  for (final scanResult in result.exportedScanResults ?? []) {
    final pluginResult = scanResult.pluginResult;
    print('Plugin result: ${pluginResult?.toJson()}');

    // Handle images based on delivery method
    final imageContainer = scanResult.imageContainer;
    if (imageContainer?.saved != null) {
      final saved = imageContainer!.saved!;
      final basePath = saved.path ?? '';
      final fullFramePath = '$basePath/${saved.images?.image}';
      final cutoutPath = '$basePath/${saved.images?.cutoutImage}';
    } else if (imageContainer?.encoded != null) {
      final encoded = imageContainer!.encoded!;
      // Decode from Base64 for display or upload
      final fullFrameBase64 = encoded.images?.image;
      final cutoutBase64 = encoded.images?.cutoutImage;
    }
  }
});

// Cancel when no longer needed
subscription.cancel();

Image Handling

Scan results may include captured images, delivered via the imageContainer field on each ExportedScanResult. Images can be delivered as:

  • Encoded images (imageContainer.encoded): Base64-encoded image data embedded in the result

  • Saved images (imageContainer.saved): file paths to images saved on disk, with a path field for the directory and images for the filenames

Configure image delivery via scanResultConfig.imageContainer in the WrapperSessionScanStartRequest.

Session End Response

When a scan session ends (via requestScanStop, user dismissal, or error), requestScanStart resolves with a WrapperSessionScanResponse. This response contains:

  • status: indicates how the session ended (scanSucceeded, scanAborted, or scanFailed)

  • succeedInfo: populated when status is scanSucceeded

  • abortInfo: populated when status is scanAborted, contains the abort reason

  • failInfo: populated when status is scanFailed, contains the error details

  • scanResultConfig: the result configuration that was active during the session

Best Practices

  • In Flutter, always cancel stream subscriptions when done

Next Steps