Integration des Scanbot Scanner SDK in eine Capacitor App mit Ionic

December 19, 2018

Wir bei Scanbot lieben die Entwicklung von nativen Apps für Android und iOS, verstehen jedoch auch absolut den Bedarf an Cross-Platform– und Hybrid-App Ansätzen. Als ein SDK Anbieter beobachten wir intensiv die Entwicklung in diesem Bereich und sind immer offen für neue Frameworks, Tools und Ansätze. Deshalb bieten wir unseren Kunden auch entsprechende Wrapper und Plugins für das Scanbot SDK an. Eines von diesen Plugins ist das Cordova Plugin für das Scanbot SDK.

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 vonstatten geht, haben sich im Laufe der Zeit einige Nachteile und sowie neue Herausforderungen ergeben, wie z.B.:

Deshalb haben sich die Entwickler von Ionic entschieden, 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 for 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.

Erste Schritte

Requirements

Für Android Apps:

Für iOS Apps:

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

Installation

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

Ionic installieren

npm install -g ionic

Eine leere Ionic App anlegen

ionic start myApp blank

Bei Aufforderung:

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 also 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

Scanbot SDK Plugin installieren

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/ und importieren die Scanbot SDK Klassen:

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

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

private SBSDK = ScanbotSDK.promisify();

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.

Scanbot SDK initialisieren

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-Dokumentation des Scanbot SDK ist hier zu finden.

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 30-Tage-Testlizenz. 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 Dokumentenscanner 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 <img>-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);
}

Für weitere Details über die Ionic WebView und File URIs, sehen Sie bitte die WebView Dokumentation.

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);
}

Das gesamte Beispielprojekt

Das ganze Beispielprojekt ist auf GitHub unter scanbot-sdk-example-capacitor-ionic zu finden. Es zeigt Beispiele für die Integration von allen API-Methodes des Scanbot SDK, wie Farbfilter, PDF Erstellung, OCR und MRZ Scanner.

Fazit

Mit diesem Tutorial haben wir eine kurze Einführung in Capacitor gemacht, indem wir eine einfache App erstellt und das Cordova Plugin for Scanbot SDK integriert haben. Die Integration von Cordova Plugins in Capacitor scheint sehr gut zu funktionieren. Wir finden Capacitor sehr interessant und glauben, dass es Cordova langfristig ersetzen wird. Da Capacitor ein eigenes Plugin System anbietet, werden wir sehr wahrscheinlich auch ein Plugin dafür entwickeln und anbieten.

Beobachten Sie am besten unsere GitHub Repos sowie unseren NPM account um auf dem neusten Stand zu bleiben.

Zum Zeitpunkt des Schreibens dieses Beitrags ist Capacitor noch Beta! Bitte sehen Sie diesen Blog-Artitel von Ionic über eine Vorschau von Capacitor für das Jahr 2019. Schauen Sie sich bei Interesse gerne auch unsere Blogposts zur Integration mit Flutter und React Native an!

Zurück zur Übersicht

Erhalten Sie die ausführliche Fallstudie

No items found.

Das Scanbot Fact Sheet: Alle Informationen auf einen Blick!

Scanbot verarbeitet und nutzt die angegebenen Informationen, um Ihnen den monatlichen Newsletter zuzusenden und Sie bzgl. unserer Produkte zu kontaktieren. Sie können diesen Service jederzeit deabonnieren. Hinweise zum Widerruf und zu der Verarbeitung Ihrer Daten finden Sie in unserer Datenschutzerklärung.

Max Stratmann

Vertriebsleiter

Wir freuen uns darauf, mit Ihnen gemeinsam die perfekte Scan-Lösung für Ihre App zu finden. Unser Expertenteam steht Ihnen zu allen Fragen bzgl. der Funktionalität, Integration oder des Lizenzmodells zur Verfügung.