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 DocumentScannerCameraController introduction. 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
You will need to 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(...) (for a new document), add pages to an existing document by calling ScanbotSdk.document.addPagesFromImageRefs(...), or just use them as ImageRefs for further processing.
Optional: if you need to configure document creation (e.g., document image size limit, enable/disable detection), use the options parameter and pass CreateDocumentOptions in createDocumentFromImageRefs(...) or AddPageOptions in addPagesFromImageRefs(...).
loading...
After that, you can modify document pages (e.g., rotate or apply filters) using the Document API.
loading...
Separately, if you still have legacy Page objects (from older v7.x workflows), you should convert them into a 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. Specifically, errorListener has been replaced with the onError callback, which receives a general SBException error object, and documentContourListener has been replaced with the onFrameDetectionResult callback.
Please also note that the result type in onFrameDetectionResult has been changed to DocumentDetectionResult.
Before (v7.x)
DocumentScannerCamera(
errorListener: (SdkLicenseStatus status) {
// ...
},
documentContourListener: (DocumentContourScanningResult result) {
// ...
},
//...
)
After (v8.x)
loading...
Please check the full v8 example here.
ScanbotCroppingWidget migration
Here is a short guide to help you update your ScanbotCroppingWidget implementation.
1. Update the input property and data type
The most important step is to change the input property from page to documentImage and ensure you are 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 any potential issues that may arise 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(...) and 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
