Capacitor App-Scanner mit Ionic

Cordova

Cordova ist ein Open Source Framework für die Entwicklung von mobilen Hybrid-Apps. Es hat eine große Community und hat sich im Produktionsbetrieb bewährt. Da die Entwicklung im App-Bereich jedoch sehr schnell vonstattengeht, haben sich im Laufe der Zeit einige Nachteile, sowie neue Herausforderungen ergeben, wie z.B.:

• Unterstützung für moderne Programmiersprachen wie Swift
• Verwaltung von nativem Projektcode
• Unterstützung für Dependency Manager wie CocoaPods
• Progressive Web Apps
• usw.

Deshalb haben sich die Entwickler von Ionic entschieden, das Capacitor als Nachfolger von Cordova zu bauen.

Capacitor

Capacitor ist ein neues Open Source Projekt, welches vom Ionic -Team, sowie der Community dahinter entwickelt und gepflegt wird. Es ist eine Cross-Platform-Runtime und ein Tool, mit dem moderne Hybrid-Apps auf Basis von HTML, CSS und JavaScript entwickelt werden können. Capacitor bringt eine Menge  Native APIs, sowie ein eigenes Plugin-System mit. Und das Beste ist – es bietet Abwärtskompatibilität für Cordova-Plugins! Man kann also Capacitor mit den meisten vorhandenen Cordova-Plugins verwenden.

In diesem Blog-Artikel möchten wir Capacitor anhand eines realen Anwendungsfalls vorstellen und evaluieren, indem wir unser Cordova Plugin für das Scanbot SDK in eine einfache Capacitor App integrieren. Und natürlich möchten wir auch zeigen, wie einfach es ist, die Funktionen des Scanbot SDK in eine moderne mobile Hybrid-App zu integrieren.

Getting Started

Voraussetzungen

• Node v8.6.0 oder neuer, mit NPM v5.6.0 oder neuer

Für Android-Apps:

• Aktuelles Android Studio mit installiertem Android SDK

Für iOS-Apps:

• Mac mit der neusten Version von Xcode
• CocoaPods

Für weitere Details sehen Sie bitte auch die vollen Anforderungen für Capacitor..

Installation

Wir erstellen hier eine App auf Basis von Capacitor mit Ionic.

Ionic installieren

npm install -g ionic

Eine leere Ionic App anlegen

ionic start myApp blank

Bei Aufforderung:

• Wählen Sie eine Ionic 3 App für dieses Tutorial aus (Ionic 4 Beta sollte mit einigen kleinen Anpassungen jedoch auch gehen).
• ⚠️ Bitte nicht Cordova zum Project hinzufügen, da wir stattdessen Capacitor einsetzen wollen!

Capacitor installieren

Um Capacitor in das Projekt installieren bzw. hinzufügen zu können, muss man vorher einmal npm run build ausführen. Damit wird das Projekt entsprechend vorbereitet (der Ordner www für Web-Assets wird erstellt, usw.):

cd myApp/
npm run build

Anschließend wird Capacitor in unser Projekt installiert:

npm install --save @capacitor/cli @capacitor/core

Capacitor mit den App-Informationen initialisieren

npx cap init MyCapacitorApp com.example.mycapacitorapp

Dabei ist "MyCapacitorApp" der Name der App und "com.example.mycapacitorapp" die App ID bzw. Bundle ID.

Man braucht diese eindeutige ID später um die App beim Apple AppStore und Google PlayStore zu registrieren. Des Weiteren werden wir diese ID zum Anfragen eines Testlizenzschlüssels für das Scanbot SDK benötigen.

Android und iOS als Plattformen hinzufügen

Wenn Capacitor erfolgreich initialisiert wurde, fügen wir Android und iOS als Plattformen hinzu:

npx cap add android
npx cap add ios

Das blanko Capacitor Projekt ist jetzt einsatzbereit. Zum Ausführen kann es in den entsprechenden IDEs (Android Studio oder Xcode) mit folgenden Kommandos geöffnet werden:

npx cap open android
npx cap open ios

Wie bereits erwähnt, unterstützt Capacitor die Cordova Plugins. Man kann ein Plugin einfach via npm install ...installieren.

Wir installieren also das cordova-plugin-scanbot-sdk in unser Projekt und müssen es anschließend mit Capacitor synchronisieren:

npm install cordova-plugin-scanbot-sdk
npx cap sync

Bitte beachten Sie, dass npx cap sync erforderlich ist, um Abhängigkeiten zu aktualisieren und um die Web-Assets in die nativen Projektordener (android und ios) zu kopieren.

Scanbot SDK Plugin integrieren

Nun sind wir bereit zu coden.

Öffnen Sie dazu die TypeScript-Datei home.ts im von Ionic generierten Ordner src/pages/home/.

Importieren Sie jetzt die Scanbot SDK-Klassen:

import ScanbotSDK from 'cordova-plugin-scanbot-sdk';

Erstellen Sie dann eine Instanz der „promisified“ Version von der Scanbot SDK API:

Erstellen Sie dann eine Instanz der „promisified“ Version von der Scanbot SDK API:

Die Methode ScanbotSDK.promisify() liefert ein Objekt, das alle API-Funktionen von Scanbot SDK bereitstellt. Anstelle von Success & Error Callback-Parametern, geben diese Funktionen jedoch ein Promise zurück.

Initialisierung des Scanbot SDK

Vor der eigentlichen Benutzung muss das Scanbot SDK initialisiert werden. Benutzen Sie dazu die Methode SBSDK.initializeSdk():

constructor(public navCtrl: NavController, platform: Platform) {
  platform.ready().then(() => this.initScanbotSDK());
}

private async initScanbotSDK() {
  await this.SBSDK.initializeSdk({
    loggingEnabled: true,
    licenseKey: '', // see the license key notes!
    storageImageFormat: 'JPG',
    storageImageQuality: 80
  }).then((result) => {
    console.log(result);
  }).catch((err) => {
    console.error(err);
  });
}

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

Lizenzschlüssel

⚠️ Bitte beachten Sie: Ohne einen Lizenzschlüssel (licenseKey) wird das Scanbot SDK nur eine Minute pro App-Sitzung funktionieren! Nach dieser Testperiode werden die Scanbot SDK Funktionen sowie die UI-Komponenten aufhören zu funktionieren. Des Weiteren wird die App terminiert.

Starten Sie die App neu, um eine weitere Test-Minute zu bekommen. Oder registrieren Sie sich für eine kostenlose und unverbindliche 7-tägige Testlizenz bzw. einen 30-tägigen Proof of Concept. Füllen Sie dazu dieses Testlizenz-Formular auf unserer Webseite aus. Geben Sie dabei die eindeutige App-Kennung (App ID) an, die wir oben beim Initialisieren des Capacitor definiert haben (z.B. com.example.mycapacitorapp).

Wenn Sie die Initialisierung des Scanbot SDK erfolgreich implementiert haben, können Sie nun die SDK UI-Komponenten aufrufen oder Bild-Operationen ausführen.

Dokumentenscanner starten

Das Scanbot SDK bietet eine vollständige und einsatzbereite Document Scanning UI-Komponente zum Scannen von Dokumenten. Benutzen Sie die async API-Methode SBSDK.UI.startDocumentScanner() um den Scanner zu starten:

async startDocumentScanner() {
  const result = await this.SBSDK.UI.startDocumentScanner({
    uiConfigs: {
      // Customize colors, text resources, behavior, etc..
      cameraPreviewMode: 'FIT_IN',
      orientationLockMode: 'PORTRAIT',
      pageCounterButtonTitle: '%d Page(s)',
      multiPageEnabled: true
      // ...
    }
  });

  if (result.status === 'CANCELED') {
    // user has canceled the scanning operation
    return;
  }

  // Get the scanned pages from result:
  this.pages = result.pages;
}

<button ion-button block (click)="startDocumentScanner()">
    Open Document Scanner
</button>

Wenn Sie Änderungen am Web-Code vornehmen, muss das Web-Projekt mit npm run build neu gebaut werden. Anschließend muss der transpilierte JavaScript-Code sowie die Web-Assets via npx cap copy in die nativen Projekte von Capacitor kopiert werden:

npm run build
npx cap copy

Nun können Sie die App in Android Studio oder Xcode ausführen und den Dokumentenscanner ausprobieren.

Bildergebnisse anzeigen

Der Dokumentenscanner liefert eine Liste von Page-Objekten zurück, die die gescannten Dokument- und Originalbilder enthalten. Ein Dokumentbild ist das zugeschnittene Bild, während das Originalbild das unverarbeitete Bild ist. Alle Bilder werden als Dateien gespeichert und als File URIs (file:///...) repräsentiert. Des Weiteren bietet ein Page-Objekt Vorschaubilder an, die z.B. als Thumbnails zum Anzeigen verwendet werden können. Wir können also einfach über alle Page-Objekte iterieren und dabei die Eigenschaft documentPreviewImageFileUri zum Anzeigen eines Dokumentbildes via -Element verwenden:

<ion-grid>
  <ion-row>
    <ion-col padding col-4 *ngfor='let page of pages'>
      <img [src]='convertFileUri(page.documentPreviewImageFileUri)'/>
    </ion-col>
  </ion-row>
</ion-grid>

Die Funktion convertFileUri() ist erforderlich, um die File URIs (file://) in Ionic WebView kompatible URLs umzuwandeln:

convertFileUri(fileUri) {
  return (<any>window).Ionic.WebView.convertFileSrc(fileUri);
}

Besuchen Sie gerne die WebView Dokumentation für weitere Details über die Ionic WebView und File URIs.

Zuschnitt UI starten

Die Zuschnitt UI bietet eine manuelle Zuschnittkorrektur eines Dokumentbildes. Es basiert auf der Dokumenterkennung und enthält einige smarte UI Elemente, wie z.B. magnetischen Kanten. Benutzen Sie die async API-Methode SBSDK.UI.startCroppingScreen() zum Starten der Zuschnitt UI und übergeben Sie dabei ein existierendes Page-Objekt:

async startCroppingScreen(page: Page) {
  const result = await this.SBSDK.UI.startCroppingScreen({
    page: page,
    uiConfigs: {
      // Customize colors, text resources, behavior, etc..
      doneButtonTitle: 'Save'
      // ...
    }
  });

  if (result.status == 'CANCELED') { return; }

  // handle the updated page object:
  this.updatePage(result.page);
}

Fazit

In diesem Tutorial haben wir eine kurze Einführung in Capacitor gegeben, indem wir eine einfache App erstellt und das Cordova Plugin für das Scanbot SDK hinzugefügt haben. Die Integration von Cordova Plugins in Capacitor scheint sehr gut zu funktionieren. Wir finden Capacitor sehr interessant und glauben, dass es langfristig Cordova ersetzen wird.

Da Capacitor sein eigenes Plugin System bereitstellt, werden wir vermutlich ebenfalls ein Plugin hierfür bereitstellen. Beobachten Sie am besten unsere GitHub Repos und unseren NPM-Account um up-to-date zu bleiben.