Classic UI: v7.x -> v8.x
Introduction
This guide is for developers using the classic DocumentScannerCamera and ScanbotCroppingWidget components who are upgrading from v7.x to v8.x of our Flutter SDK.
Version 8.0.0 introduces significant API and behavioral changes to these components. This guide will walk you through the necessary adjustments.
Key concept differences
A fundamental change in v8.0.0 is that the classic components now work with the ImageRef class instead of the legacy Page class.
Another major change is the introduction of DocumentScannerCameraController. This controller is now the primary way to programmatically interact with the camera, such as document snapping.
Furthermore, several callbacks have been renamed.
DocumentScannerCamera migration
Follow these steps and code examples to migrate your DocumentScannerCamera implementation.
1. Update the snapping callback
Replace the old snapListener with the new onSnappedDocumentResult callback. The new callback provides results as ImageRef objects instead of the old Page objects.
Before (v7.x)
You would use snapListener to get a Page object:
DocumentScannerCamera(
snapListener: (Page page) {
// `page` is a legacy Page object
},
//...
)
After (v8.x)
Use onSnappedDocumentResult to get the ImageRef for the original and cropped document images:
loading...
Note: If detectDocumentAfterSnap is enabled, the onSnappedDocumentResult callback provides the cropped image of the detected document (as an ImageRef) along with the document detection result.
From there, you can pass the returned ImageRef object into ScanbotSdk.document.createDocumentFromImageRefs(...) to create a new document, add pages to an existing document by calling ScanbotSdk.document.addPagesFromImageRefs(...), or use the ImageRef objects directly for further processing.
Optional: If you need to configure document creation (e.g., document image size limit or enable/disable detection), use the options parameter and pass CreateDocumentOptions in createDocumentFromImageRefs(...) or AddPageOptions in addPagesFromImageRefs(...).
loading...
Once a document has been created, you can modify its pages (e.g., rotate or apply filters) using the Document API.
loading...
If your project still contains legacy Page objects from v7.x workflows, convert them to DocumentData using createDocumentFromLegacyPages(...).
loading...
2. Use the controller for manual snapping
If you need to trigger a document snap manually, you must now use the DocumentScannerCameraController. The previous snapTrigger function has been removed.
Before (v7.x)
The onCameraPreviewStarted callback provided a snapTrigger function:
Function? generalSnapTrigger;
DocumentScannerCamera(
onCameraPreviewStarted: (snapTrigger, isFlashAvailable) {
generalSnapTrigger = snapTrigger;
},
//...
)
// To snap: generalSnapTrigger?.call();
After (v8.x)
Create and pass the optional controller parameter to the DocumentScannerCamera widget, then call its snapDocument() method when needed:
final DocumentScannerCameraController controller = DocumentScannerCameraController();
DocumentScannerCamera(
controller: controller,
onCameraPreviewStarted: (isFlashAvailable) {
// The snapTrigger is no longer provided here
},
//...
)
// To snap: controller.snapDocument();
3. Rename additional callbacks
Finally, you must update the names of the other callbacks to align with the new API. errorListener has been replaced with the onError callback, which receives a general SBException error object. documentContourListener has been replaced with the onFrameDetectionResult callback.
Note that the result type in onFrameDetectionResult has changed to DocumentDetectionResult.
Before (v7.x)
DocumentScannerCamera(
errorListener: (SdkLicenseStatus status) {
// ...
},
documentContourListener: (DocumentContourScanningResult result) {
// ...
},
//...
)
After (v8.x)
loading...
See the full v8 example.
ScanbotCroppingWidget migration
Follow the steps below to update your ScanbotCroppingWidget implementation.
1. Update the input property and data type
The most important change is updating the input property from page to documentImage, and passing it an ImageRef object instead of a Page object.
Before (v7.x)
The widget accepted a Page object via the page property:
late Page currentPage;
ScanbotCroppingWidget(
page: currentPage,
// ...
);
After (v8.x)
The widget now requires an ImageRef object passed to the documentImage property:
loading...
2. Add the optional onError callback
It is recommended to implement the new onError callback to handle errors that may occur within the widget (e.g., license errors).
Before (v7.x)
There was no built-in error handling callback.
After (v8.x)
You can now add the onError callback for error handling.
loading...
3. Cropping result handling
Before (v7.x)
Cropping and rotation were applied directly to a Page object via ScanbotSdk.cropAndRotatePage(...), which returned a new Page.
loading...
After (v8.x)
cropAndRotatePage has been removed. Cropping and rotation are now performed through the Document API, i.e. you create a document from the ImageRef object using ScanbotSdk.document.createDocumentFromImageRefs(...), then update the page using ScanbotSdk.document.modifyPage(...) (or other Document API operations). This returns an updated DocumentData.
loading...
Want to scan longer than one minute?
Generate a free trial license to test the Scanbot SDK thoroughly.
Get free trial licenseScanbot SDK is part of the Apryse SDK product family
A mobile scan is just the start. With Apryse SDKs, you can expand mobile workflows into full cross‑platform document processing. Whether you need to edit PDFs, add secure digital signatures, or use a fast, customizable document viewer and editor, Apryse gives you the tools to build powerful features quickly.
Learn more
