Flutter Scanner-Apps: So integrieren Sie das Scanbot SDK

Erste Schritte

Voraussetzungen

• Flutter

Für Android Apps

• Aktuelles Android Studio mit installiertem Android SDK

Für iOS Apps

• Mac OS X mit der aktuellen Version von Xcode
• CocoaPods

Du kannst Android Studio als IDE für die Entwicklung von Flutter Apps verwenden. Außerdem gibt es Flutter IDE Plugins für VS Code und IntelliJ IDEA. In diesem Tutorial werden wir die Flutter-CLI (Command Line Interface) Tools verwenden, da diese Tools einfach zu benutzen sind und unabhängig von jeglichen IDE-Plugins funktionieren.

Sobald Du das Framework installiert hast, kannst Du den Befehl flutter doctor ausführen, um zu überprüfen, ob alle erforderlichen Tools richtig eingerichtet sind.

Erstelle eine “Hello World” Flutter App

$ flutter create --androidx my_awesome_flutter_app

Dieser Befehl erzeugt ein einfaches Flutter Projekt für Android und iOS.

Bitte beachte die Option –androidx, die das Android-Projekt unter Verwendung der neuen AndroidX Bibliotheken generiert. Sie ist nicht nur erforderlich, um die neueste Version des Scanbot Android SDKs zu verwenden, sondern wird auch für jedes neue Android Flutter Projekt dringend empfohlen.

(Wenn Du Dein Flutter Projekt nach AndroidX migrieren musst, schau Dir bitte die entsprechende Flutter Dokumentation " “AndroidX Migration”)" an.

Testlauf

Schließe ein mobiles Gerät über USB an und führe die App aus.

Android

$ cd my_awesome_flutter_app/
$ flutter run -d <DEVICE_ID>

Du kannst die IDs aller angeschlossenen Geräte über flutter devices erhalten.

iOS

Öffne den Xcode-Workspace  ios/Runner.xcworkspace und passe die Einstellungen für das  Signing / Developer Account  in der Xcode IDE an. Erstelle dann die Anwendung in Xcode und führe sie aus.

Sowohl auf Android als auch auf iOS solltest Du die gleiche "Hello World" Anwendung sehen, die eine einfache Benutzeroberfläche mit einer Schaltfläche und Beschriftungs-Widgets sowie die Funktionalität zum Erhöhen eines Zählers zeigt.

Füge das Scanbot SDK Flutter Plugin hinzu

Als nächster Schritt werden wir das Scanbot Scanner SDK für Flutter Plugin hinzufügen, das als öffentliches Flutter-Package zur Verfügung gestellt wird. Flutter Plugins sind als Packages erhältlich und bieten Zugriff auf native System APIs wie Kamera, Netzwerk, Batteriestatus usw., sowie auf SDKs für Plattformen von Drittanbietern wie z.B. Firebase.

Es gibt eine Menge Packages, die auf dem offiziellen Repository  pub.dev gehostet werden, das ein Äquivalent zu npmjs.org  für Node-Packages oder nuget.org für Xamarin-Packages ist. Weitere Einzelheiten zu den Flutter-Packages findest Du in den Flutter Dokumenten “Packages verwenden.”

Fügen wir also das Package scanbot_sdk zu unserem Projekt hinzu. Öffne dafür die Datei pubspec.yaml und definiere das Package unter folgenden dependencies:

dependencies:
  scanbot_sdk: ^1.0.0

Nachdem die neuen Packages hinzugefügt wurden, müssen diese heruntergeladen und installiert werden. Dazu kehren wir wieder zum Flutter CLI zurück und führen den folgenden Befehl aus:

$ flutter pub get

Android tunings

Um das neueste Scanbot Android SDK zu unterstützen, müssen wir einige Gradle Einstellungen anpassen.

Da das von Flutter generierte Android Projekt auf einer älteren Kotlin Version 1.2.x basiert, müssen wir diese Version auf 1.3.x erhöhen. In der Top-Level-Datei android/build.gradle:

buildscript {
    ext.kotlin_version = '1.3.41'
    ...
}

Aktiviere auf Anwendungsebene in der Datei android/app/build.gradle die Option multidex und füge die folgenden packagingOptions hinzu:

android {
    ...
    defaultConfig {
      applicationId "com.example.myAwesomeFlutterApp"
      ...
      multiDexEnabled true
    }

    packagingOptions {
        pickFirst 'META-INF/atomicfu.kotlin_module'
        pickFirst 'META-INF/proguard/coroutines.pro'
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/NOTICE.txt'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
    }
}

Füge in der Datei  android/app/src/main/AndroidManifest.xml  die Erlaubnis  CAMERA  hinzu:

<manifest ...>
  <uses-permission android:name="android.permission.CAMERA" />
  ...
</manifest>

iOS setup

Gib eine globale Plattform Version in der ios/Podfile Datei an, z.B.:

platform :ios, '9.0'

Dann installiere die Pods mit dem Befehl:

$ cd ios/
$ pod install

Füge zum Abschluss die erforderliche  NSCameraUsageDescription Eigenschaft in Xcode auf der Registerkarte Info der Einstellungen des Projekts (alias Info.plist Datei) hinzu:

NSCameraUsageDescription "Privacy - Camera Usage Description"

Zeit fürs Programmieren!

Und jetzt lasst uns etwas Dart Code schreiben! Wir werden die Datei lib/main.dart anpassen, die der Einstiegspunkt der Flutter App ist.

Importiere die Scanbot SDK Klassen

Füge die folgenden Importe einiger Scanbot SDK Packages und Flutter UI Widgets hinzu, die wir verwenden werden:

import 'dart:io';
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:scanbot_sdk/common_data.dart';
import 'package:scanbot_sdk/document_scan_data.dart';
import 'package:scanbot_sdk/scanbot_sdk.dart';
import 'package:scanbot_sdk/scanbot_sdk_models.dart';
import 'package:scanbot_sdk/scanbot_sdk_ui.dart';

Initialisierung des Scanbot SDK

Das Scanner SDK für Flutter muss vor der Verwendung initialisiert werden. Verwende dazu die SDK API Methode ScanbotSdk.initScanbotSdk(config). Wir initialisieren das Scanbot SDK, wenn das Haupt Widget der Anwendung erstellt wird:

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {

    ScanbotSdk.initScanbotSdk(ScanbotSdkConfig(
      loggingEnabled: true,
      licenseKey: "", // see the license key notes below!
    ));

    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

Die vollständige API-Referenz des Scanbot SDK Flutter Plugins findest Du in unserer Dokumentation.‍

Integration der Document Scanner UI

Das Scanbot Scanner SDK für das Flutter Plugin bietet eine Scanner-Benutzeroberfläche (UI) für das Scannen von Dokumenten. Der Dokumentenscanner ist eine komplette und gebrauchsfertige Bildschirmkomponente und kann mit nur wenigen Zeilen Code über die API-Methode ScanbotSdkUi.startDocumentScanner(config) einfach integriert werden.

Legen wir nun den SDK Aufruf in eine einfache Funktion namens scanDocument(), damit wir ihn an eine Schaltfläche binden können:

class _MyHomePageState extends State<MyHomePage> {

  void scanDocument() async {
    var config = DocumentScannerConfiguration(
      multiPageEnabled: false,
      bottomBarBackgroundColor: Colors.blueAccent,
      cancelButtonTitle: "Cancel",
      // see further configs ...
    );
    var result = await ScanbotSdkUi.startDocumentScanner(config);

    if (result.operationResult == OperationResult.SUCCESS) {
      // get and use the scanned images as pages: result.pages[n] ...
      displayPageImage(result.pages[0]);
    }
  }

  ...
}

Übrigens: Wir schätzen und empfehlen das async/await - Muster in Dart sehr, welches auch aus anderen Sprachen wie C#, TypeScript, JavaScript, etc. bekannt ist.

Füge nun das Flutter Widget CupertinoButton hinzu und binde unsere  scanDocument() Methode als onPressed Ereignis ein:

CupertinoButton(
  child: Text("Scan a Document"),
  onPressed: scanDocument,
),

Mit der DocumentScannerConfiguration kann man Konfigurationsparameter übergeben, um Farben, Textressourcen und einige Funktionsverhalten des Dokumentenscanners anzupassen. Weitere Einzelheiten findest Du in der API-Dokumentation.

Als Ergebnis gibt der Dokumentenscanner ein Array von Seitenobjekten (Page-Objekten) zurück, die das gescannte Dokument- und die Originalbilder enthalten. Ein Dokumentbild ist das beschnittene und perspektivisch korrigierte Bild (hochauflösend), während das Originalbild das unverarbeitete Bild (hochauflösend) ist. Alle Bilder werden standardmäßig als JPG-Dateien gespeichert und als Datei-URIs dargestellt (file:///...). Darüber hinaus stellt ein Seitenobjekt Vorschaubilder (niedrige Auflösung) zur Verfügung, die als Thumbnails zur Anzeige verwendet werden sollten.

Der Einfachheit halber haben wir in diesem Beispiel die Mehrseitenfunktion des Dokumentenscanners über den Konfigurationsparameter multiPageEnabled: false. deaktiviert. So wird die Scanner-Benutzeroberfläche nach einem einzigen Scan automatisch geschlossen, und wir können die erste Page aus dem Array result.pages[0] verwenden, um das beschnittene Dokumentbild anzuzeigen.

Das gescannte Bild anzeigen

Verwende die JPG Datei URI eines Seitenobjektes page.documentPreviewImageFileUri, um ein Vorschaubild anzuzeigen. Dazu fügen wir ein weiteres Flutter Widget namens Image hinzu und speichern eine Instanz als Variable mit dem Namen currentPreviewImage. Um das letzte gescannte Seitenbild anzuzeigen, implementieren wir die einfache Methode displayPageImage(page), die den Status des  currentPreviewImage Widgets aktualisiert:

class _MyHomePageState extends State<MyHomePage> {

  Image currentPreviewImage;

  void scanDocument() async { ... }

  void displayPageImage(Page page) {
    setState(() {
      currentPreviewImage = Image.file(File.fromUri(page.documentPreviewImageFileUri), width: 300, height: 300);
    });
  }

  ....
}

Und schließlich rendern wir das currentPreviewImage Widget direkt unter unserem CupertinoButton:

...
CupertinoButton(
  child: Text("Scan a Document"),
  onPressed: scanDocument,
),
if (currentPreviewImage != null) ... [
  Text("Document image:"),
  currentPreviewImage,
],

Vollständige Beispielprojekte

Um einen gelungenen Start zu ermöglichen, schau dir gerne die folgenden Beispielprojekte auf GitHub an:

– Ein kleines Beispielprojekt für dieses Tutorial: https://github.com/doo/my_awesome_flutter_app

– Ein vollständiges Beispielprojekt:  https://github.com/doo/scanbot-sdk-example-flutter
Es demonstriert die Integration aller API-Methoden des Scanbot SDK Flutter Plugins, wie z.B. die Benutzeroberfläche zum manuellen Beschneiden der Bilder (Cropping UI), Bildfilterung, PDF- und TIFF-Erzeugung, Optische Zeichenerkennung (OCR), Scannen von Barcodes und QR-Codes, MRZ-Scanner (maschinenlesbare Zonen) und Scannen von EHIC Karten (europäische Krankenversicherungskarte).

Scanbot SDK (Testversion) Lizenzschlüssel

Bitte beachte: Das Scanbot SDK läuft ohne Lizenzschlüssel pro Sitzung eine Minute lang. Nach dem Testzeitraum werden alle Funktionen des Scanbot Scanner SDK für Flutter deaktiviert, einschließlich der UI-Komponenten.

Sie können eine uneingeschränkte, unverbindliche 7-Tage Testlizenz kostenlos erhalten.

Da der Scanbot SDK-Lizenzschlüssel an einen App Identifier (auch Application ID auf Android und Bundle Identifier auf iOS genannt) gebunden ist, musst Du den standardmäßig generierten App Identifier com.example.myAwesomeFlutterApp dieser Tutorial Anwendung verwenden. Natürlich kannst Du auch die ID Deiner Anwendung verwenden, um eine Testlizenz zu erhalten. Bitte beachte auch, dass bei den App-IDs die Groß- und Kleinschreibung berücksichtigt wird!

Um einen Lizenzschlüssel für beide Plattformen, Android und iOS, für diese Tutorial-Anwendung anzufordern, stelle sicher, dass die IDs der Anwendungen identisch sind. Typischerweise musst Du die App-ID des standardmäßig generierten Android-Projekts von com.example.my_awesome_flutter_app in com.example.myAwesomeFlutterApp ändern, da Flutter offenbar unterschiedliche IDs für diese beiden Plattformen generiert.

Hier finden Sie den App Identifier:

• Für Android siehe applicationId ... in der Datei android/app/build.gradle.
• Für iOS findest du den Bundle-Identifier in der Registerkarte Allgemeine Einstellungen in der Xcode IDE.