Dokumentenscanner mit Kotlin Multiplatform entwickeln

Mit der gemeinsamen Kotlin-API des Docutain SDKs starten Sie einen Dokumentenscan in Android- und iOS-Apps und verarbeiten das Ergebnis aus geteiltem Code.

Kotlin Multiplatform ermöglicht es, ausgewählten Kotlin-Code zwischen Android und iOS zu teilen. Die Oberfläche kann plattformspezifisch bleiben oder mit Compose Multiplatform entwickelt werden. Das Docutain KMP-Paket stellt seine API in commonMain bereit und verwendet auf beiden mobilen Plattformen die nativen Docutain-Implementierungen. Diese Anleitung behandelt Dokumentenscanning. Für eine native Android-App mit Kotlin gibt es eine separate Android-Anleitung.

Zielplattformen

Android und iOS

Gemeinsame API

Kotlin commonMain

Mindestversion

Android API 24; iOS 13

Verarbeitung

Lokal und offline

Projektstruktur und Plattformvoraussetzungen

Planen Sie drei Schichten: In commonMain liegen SDK-Aufrufe, Ergebniszustände und die gemeinsame Fachlogik. Die Android- und iOS-Apps übernehmen Plattformintegration, Ressourcen und Dateifreigabe. Die native Docutain-Oberfläche führt durch Aufnahme und Bearbeitung; Ihre Oberfläche zeigt anschließend das Ergebnis an. Eine gemeinsame API bedeutet daher nicht, dass jede Plattformkonfiguration entfällt.

Für Android nennt die aktuelle Einrichtung JDK 17, compileSdk 37 und ein dazu passendes Android Gradle Plugin, beispielsweise 9.1.1 oder neuer. Für iOS benötigen Sie eine macOS-Buildumgebung mit Xcode und CocoaPods. Prüfen Sie die Kombination mit Ihrem bestehenden Projekt im KMP-Einrichtungsleitfaden. Ergänzen Sie auf iOS eine verständliche NSCameraUsageDescription und prüfen Sie die Kamerafreigabe auf beiden Geräten vor dem ersten produktiven Test.

Abhängigkeiten einrichten

Fügen Sie das KMP-Paket den commonMain-Abhängigkeiten des gemeinsamen Moduls hinzu:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("de.docutain:Docutain-SDK-KMP:1.0.0")
        }
    }
}

Die iOS-App benötigt zusätzlich den nativen Docutain-CocoaPod:

platform :ios, '13.0'
target 'YourApp' do
  use_frameworks!
  pod 'DocutainSdk', '1.9.0'
end

Führen Sie nach der Änderung der Podfile pod install aus. Der aktuelle KMP-Einrichtungsleitfaden nennt Build-Voraussetzungen und Paketversionen; prüfen Sie ihn vor einem Projekt-Upgrade.

SDK initialisieren

Initialisieren Sie Docutain beim App-Start, bevor ein Scan beginnt. Verwenden Sie einen für die App-ID jeder Ziel-App gültigen Lizenzschlüssel. Das Testlizenzformular nimmt eine Kennung entgegen; für die Evaluation einer zweiten App-ID wenden Sie sich an den SDK-Support.

import de.docutain.sdk.kmp.DocutainException
import de.docutain.sdk.kmp.DocutainSdk

try {
    DocutainSdk.initSdk("<YOUR-LICENSE-KEY>")
} catch (exception: DocutainException) {
    // SDK-Aktionen deaktivieren und passenden Fehler anzeigen.
}

Für die Evaluation können Sie eine kostenlose Testlizenz anfordern. Die Initialisierungsdoku erläutert Lizenzverhalten und Fehlerbehandlung.

Scannen und Ergebnis verarbeiten

Die fertige Scan-Oberfläche lässt sich aus gemeinsamem Kotlin-Code starten. scanDocument ist eine Suspend-Funktion: Rufen Sie sie in einer Coroutine auf und verarbeiten Sie das Ergebnis erst nach Abschluss des Scans.

import androidx.compose.runtime.rememberCoroutineScope
import de.docutain.sdk.kmp.DocutainException
import de.docutain.sdk.kmp.DocutainSdk
import de.docutain.sdk.kmp.DocumentScannerConfiguration
import kotlinx.coroutines.launch

val scope = rememberCoroutineScope()
scope.launch {
    try {
        val completed = DocutainSdk.scanDocument(DocumentScannerConfiguration())
        if (completed) {
            val pdfUrl = DocutainSdk.writePDF()
            for (page in 1..DocutainSdk.pageCount()) {
                val imageUrl = DocutainSdk.writeImage(page)
                // Das exportierte Seitenbild im Workflow verwenden.
            }
            val text = DocutainSdk.getText()
            val data = DocutainSdk.analyze()
            // PDF, OCR-Text und extrahierte Daten in der App nutzen.
        }
    } catch (exception: DocutainException) {
        // Fehler beim Scannen oder Export behandeln.
    }
}

Dieses Beispiel läuft in einem Compose-Screen, in dem rememberCoroutineScope() verfügbar ist. Bei einer KMP-App mit nativer Oberfläche rufen Sie dieselbe Suspend-API aus einem geeigneten Coroutine-Scope Ihrer gemeinsamen Anwendungsschicht auf. Das PDF-Ergebnis ist auf Android und iOS eine file://-URL. OCR-Text und strukturierte Extraktion hängen von den lizenzierten Modulen ab; Ihre App entscheidet über Speicherung und Weitergabe.

DocumentScannerConfiguration unterstützt auch Kamera- und Galerieeingaben, mehrseitige Scans und Einstellungen der Scan-Oberfläche. Die möglichen Optionen und aktuellen API-Details stehen unter Document Scan und PDF Creation.

Scanner für den Anwendungsfall konfigurieren

Für mehrseitige Verträge oder Belege sind automatische Aufnahme, eine Seitenübersicht und die Möglichkeit zur erneuten Aufnahme sinnvoll. Das folgende Beispiel erweitert den Kameraablauf um einen Import-Button. Ersetzen Sie damit die Standardkonfiguration im Scan-Aufruf; die Ergebnisverarbeitung bleibt gleich.

import de.docutain.sdk.kmp.DocumentScannerConfiguration
import de.docutain.sdk.kmp.Source

val scanConfig = DocumentScannerConfiguration().apply {
    source = Source.CAMERA_IMPORT
    autoCapture = true
    multiPage = true
    confirmPages = true
    pageEditConfig.allowPageRetake = true
}
// Inside your coroutine, use this instead of the default configuration:
val completed = DocutainSdk.scanDocument(scanConfig)

Für genau eine Seite setzen Sie multiPage = false. Für mehrere vorhandene Bilder verwenden Sie Source.GALLERY_MULTIPLE. Filter sollten zum Dokument passen: Prüfen Sie Text, Logos und farbige Diagramme, bevor Sie einen festen Filter vorgeben. Die vollständigen Optionen stehen unter Document Scan.

Farben, Texte und Button-Titel können aus gemeinsamem Code angepasst werden; eigene Button-Icons benötigen Plattformressourcen. Nutzen Sie Color Configuration, Onboarding und Scan Tips für einen verständlichen Einstieg. Prüfen Sie für internationale Apps die SDK-Oberfläche und Ihre eigenen Texte in den Zielsprachen getrennt von der OCR-Erkennung.

PDF und Seitenbilder weiterverarbeiten

Legen Sie zuerst fest, was Ihr Workflow benötigt: ein zusammenhängendes PDF zur Ablage, einzelne Seitenbilder für einen nachgelagerten Prozess oder zusätzlich OCR-Text. Führen Sie nur die benötigten Exportschritte aus. So benötigt ein reiner Scan-zu-PDF-Ablauf weder getText() noch analyze().

import de.docutain.sdk.kmp.DocutainSdk
import de.docutain.sdk.kmp.PDFPageFormat

// Call after a completed scan, inside a coroutine.
val pdfUrl = DocutainSdk.writePDF(
    pageFormat = PDFPageFormat.LETTER,
    maxSizeKB = 10 * 1024
)

Das Beispiel nutzt US Letter; wählen Sie für andere Zielmärkte A4 oder FIT_TO_PAGES, wenn das Seitenverhältnis erhalten bleiben soll. Die Größenbegrenzung kann Bildqualität und Laufzeit beeinflussen: Prüfen Sie kleine Schrift und lange Dokumente. PDF Creation beschreibt Formate, Komprimierung und eigene Zieldateien.

Die zurückgegebene file://-URL bezeichnet eine lokale Datei. Übergeben Sie diese an Ihre plattformspezifische Speicher- oder Freigabeschicht; sie ist kein öffentlicher Download-Link. Schließen Sie Speicherung oder Upload ab, bevor Ihre App Dateien bereinigt. Details zu einzelnen Seiten finden Sie unter Image Export.

Den gesamten Workflow testen

Testen Sie auf echten Android- und iOS-Geräten mit repräsentativen Dokumenten und Lichtverhältnissen. Prüfen Sie Kameraberechtigungen, Abbruch, mehrere Seiten, PDF-Ausgabe und die Übergabe an Ihren eigenen Speicher- oder Upload-Prozess. Docutain verarbeitet Dokumente lokal; eine Übertragung aus der App liegt in Ihrer Implementierung.

Für OCR-Volltext oder strukturierte Extraktion nach dem Scan finden Sie eigene Anleitungen zu Texterkennung und Datenextraktion.

Typische Integrationsfehler eingrenzen

Wenn die Oberfläche mehrfach startet, prüfen Sie den Auslöser: Starten Sie aus einer Nutzeraktion und sperren Sie diese bis zum Abschluss. Ein direkter Start im Composable-Funktionskörper kann bei einer Recomposition erneut ausgelöst werden. Trennen Sie „bereit“, „läuft“, „abgebrochen“, „erfolgreich“ und „fehlgeschlagen“ in Ihrem UI-Zustand. Setzen Sie die Laufsperre auch bei Fehlern zurück.

Bei Initialisierungsproblemen prüfen Sie Lizenz und App-Kennungen, bei iOS-Linkerfehlern zuerst Pod-Installation und die abgestimmten Abhängigkeiten. Verwechseln Sie den Abbruch durch Nutzer nicht mit einer Coroutine-Cancellation. Letztere sollte an den übergeordneten Scope weitergegeben werden. Die KMP-Doku erklärt Coroutines and suspend functions sowie Error Handling.