audi-app/companion-app/docs/SHARE_EXTENSION.md

Tankbeleg aus dem Teilen-Blatt

Ein PDF aus Mail (oder einer anderen App) über Teilen → DataMetric360 direkt als Tankbeleg übernehmen.

Wie es zusammenhängt

Mail  ──Teilen──►  DataMetric360Share          (eigener Prozess)
                        │
                        │ PDF → Base64 → UserDefaults der App-Gruppe
                        │                group.app.datametric360
                        ▼
                   datametric360://beleg       (öffnet die App)
                        │
                        ▼
                   App.tsx  ──holt ab──►  Tanken-Seite ──►  belegLesen()

Eine Erweiterung ist ein eigener Prozess mit eigenem Dateibereich; der einzige gemeinsame Boden mit der App ist die App-Gruppe. Der Beleg reist deshalb Base64-kodiert durch die geteilten UserDefaults — die liest @capacitor/preferences ohnehin schon, sobald man ihm die Gruppe nennt. Eine Datei im Gruppen-Container wäre der sauberere Ort, bräuchte auf der App-Seite aber eigenen nativen Code, also ein zusätzliches Plugin für einen Weg, den es sonst nicht gäbe.

Der Preis ist eine Größengrenze von 4 MB (grenzeBytes im ShareViewController). Ein Tankbeleg liegt bei einigen Dutzend Kilobyte; ein gescanntes Mehrseiten-PDF kann darüber liegen — dann sagt die Erweiterung das, und der Weg über Beleg hochladen → Datei auswählen in der App bleibt.

Wo was liegt

Datei	Rolle
native/teilen/ShareViewController.swift	nimmt das PDF entgegen, legt es ab, öffnet die App
native/teilen/Info.plist	wann DataMetric360 im Teilen-Blatt erscheint (genau ein PDF)
native/teilen/DataMetric360Share.entitlements	App-Gruppe für die Erweiterung
native/App.entitlements	dieselbe App-Gruppe für die App
scripts/ios-teilen-einrichten.mjs	hängt das alles ins erzeugte Xcode-Projekt
src/daten/geteilterBeleg.ts	holt den Beleg ab, räumt ihn weg
src/App.tsx	prüft beim Start und bei jeder Rückkehr, springt auf Tanken
src/screens/Tanken.tsx	nimmt ihn auf und lädt ihn hoch

companion-app/ios/ ist gitignored und wird von npx cap add ios neu gebaut. Alles Native muss deshalb unter native/ liegen und bei jedem Bau eingespielt werden — dieselbe Regel, die schon die Team-Kennung und den Standort-Schlüssel in ios-signieren.sh getrieben hat.

Einmalig im Apple-Entwicklerportal

Ohne diese drei Schritte schlägt das Signieren fehl (die App-Gruppe muss existieren, bevor ein Profil sie enthalten kann):

1. Identifiers → App Groups: group.app.datametric360 anlegen.
2. Identifiers → App IDs: app.datametric360.teilen anlegen, Capability App Groups aktivieren, die Gruppe zuordnen.
3. Bei der bestehenden App-ID app.datametric360 ebenfalls App Groups aktivieren und dieselbe Gruppe zuordnen.

Danach in Xcode einmal die Profile neu ziehen lassen — oder schlicht ios-signieren.sh laufen lassen, das macht -allowProvisioningUpdates selbst. Merkposten aus Abschnitt AI: ein zwischengespeichertes altes Profil wird stillschweigend weiterverwendet. Ändert sich etwas an den Berechtigungen, das passende .mobileprovision unter ~/Library/Developer/Xcode/UserData/Provisioning Profiles löschen und neu exportieren.

Bauen

bash scripts/ios-signieren.sh

Der Schritt „Share-Erweiterung einrichten" läuft dort automatisch, vor dem Archivieren.

Wenn das Skript abbricht

ios-teilen-einrichten.mjs bearbeitet die project.pbxproj über das npm-Paket xcode. Erstmals auf einem Mac gelaufen am 2026-09-02; dabei kam genau ein Fehler heraus, seither behoben: die Erweiterung wurde zweimal eingebettet, weil addTarget() für den Typ app_extension von sich aus schon eine Copy-Phase nach PlugIns anlegt und das Skript eine zweite hinzufügte. Xcode quittierte das mit error: Unexpected duplicate tasks. Das Anlegen des Ziels selbst, die Entitlements, das URL-Schema und die Idempotenz funktionierten auf Anhieb.

Bricht es ab, ist nichts halb eingerichtet (es bricht vor dem Schreiben ab), und dasselbe lässt sich in Xcode von Hand erledigen:

1. File → New → Target… → Share Extension, Name DataMetric360Share, Sprache Swift, „Activate scheme" verneinen.
2. Die von Xcode erzeugten ShareViewController.swift, Info.plist und das MainInterface.storyboard löschen und stattdessen die Dateien aus native/teilen/ in das Ziel legen (Storyboard wird nicht gebraucht, die Erweiterung hat keine eigene Oberfläche).
3. Bundle-ID des Ziels auf app.datametric360.teilen setzen.
4. Beide Ziele → Signing & Capabilities → + Capability → App Groups, group.app.datametric360 anhaken.
5. Ziel DataMetric360Share → Build Settings → Code Signing Entitlements auf DataMetric360Share/DataMetric360Share.entitlements; Ziel App auf App/App.entitlements.
6. Ziel App → Build Phases → Embed App Extensions muss DataMetric360Share.appex enthalten.
7. ios/App/App/Info.plist: URL-Schema datametric360 unter CFBundleURLTypes eintragen.

Schritt 7 ist der leiseste: fehlt er, wird der Beleg abgelegt, die App aber nicht geöffnet — er taucht dann erst auf, wenn man die App das nächste Mal von Hand startet.

Prüfen, ob es wirkt

1. In Mail ein PDF antippen → Teilen → DataMetric360 muss in der Liste stehen (nur bei genau einem PDF, sonst absichtlich nicht).
2. Antippen → die App kommt nach vorn, springt auf Tanken, das Formular ist offen und liest den Beleg („Beleg wird gelesen …").
3. Danach ist der Eintrag weg: dieselbe Datei ein zweites Mal zu teilen muss wieder funktionieren, ein bloßes Wechseln in die App darf den Beleg nicht erneut verarbeiten.

Was hier nicht steht

Android. Der Ablauf ist dort ein anderer (intent-filter statt App-Gruppe), und die Android-Hülle dieses Projekts ist ohnehin nicht in Gebrauch.