226 lines
6.9 KiB
Markdown
226 lines
6.9 KiB
Markdown
# Mobile Apps – iOS & Android
|
||
|
||
Die "Thats Me" App wird mit **Capacitor** (v7) als native iOS- und Android-App verpackt. Capacitor bündelt die Quasar Web-App in eine WebView innerhalb einer nativen App-Shell.
|
||
|
||
---
|
||
|
||
## Wichtig: Zwei Umgebungen
|
||
|
||
| Umgebung | Zweck |
|
||
| --------------------- | ---------------------------------------------------------------------- |
|
||
| **Docker-Container** | Quasar Dev-Server, Vue-Code bearbeiten, `npm install`, Web-Entwicklung |
|
||
| **Mac Server / Host** | Xcode, CocoaPods, Capacitor-Builds, iOS Simulator |
|
||
|
||
Xcode und CocoaPods laufen **ausschließlich auf dem Mac** (außerhalb Docker). Die installierten Tools auf dem Mac-Host beeinflussen den Docker-Container **nicht** – beide Umgebungen sind vollständig isoliert.
|
||
|
||
---
|
||
|
||
## Projektstruktur
|
||
|
||
```
|
||
frontend/
|
||
├── src/ # Quasar Quellcode (Vue.js)
|
||
├── src-capacitor/ # Capacitor nativer Wrapper
|
||
│ ├── ios/ # Xcode-Projekt (lokal, nicht im Git)
|
||
│ ├── android/ # Android Studio Projekt (lokal, nicht im Git)
|
||
│ ├── www/ # Kompilierte Web-Assets (nicht im Git)
|
||
│ ├── capacitor.config.json # App-Konfiguration
|
||
│ └── package.json # Capacitor Dependencies
|
||
└── quasar.config.js # Quasar Config
|
||
```
|
||
|
||
## App-Konfiguration
|
||
|
||
| Eigenschaft | Wert |
|
||
| ----------- | ----------------------- |
|
||
| App ID | `media.adametz.thatsme` |
|
||
| App Name | `Thats Me` |
|
||
|
||
---
|
||
|
||
## Einmaliges Setup auf dem Mac
|
||
|
||
### 1. Voraussetzungen installieren
|
||
|
||
```bash
|
||
# Homebrew (falls nicht vorhanden)
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
|
||
# Node.js
|
||
brew install node
|
||
|
||
# CocoaPods (iOS Dependency Manager)
|
||
brew install cocoapods
|
||
# oder: sudo gem install cocoapods
|
||
|
||
# Prüfen:
|
||
node --version # z.B. v25.x
|
||
pod --version # z.B. 1.16.2
|
||
```
|
||
|
||
### 2. Xcode einrichten
|
||
|
||
- Xcode aus dem **Mac App Store** installieren (~15 GB, etwas Geduld)
|
||
- Nach der Installation Xcode **einmal öffnen** und License akzeptieren
|
||
- Developer Directory auf Xcode setzen:
|
||
|
||
```bash
|
||
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
|
||
sudo xcodebuild -license accept
|
||
```
|
||
|
||
Prüfen:
|
||
|
||
```bash
|
||
xcode-select -p
|
||
# Ausgabe: /Applications/Xcode.app/Contents/Developer
|
||
```
|
||
|
||
### 3. Capacitor Dependencies installieren
|
||
|
||
```bash
|
||
cd ~/Sites/thats-me.local/frontend/src-capacitor
|
||
npm install
|
||
```
|
||
|
||
> ⚠️ **Wichtig:** `npm install` immer nur im `src-capacitor/`-Unterordner ausführen, **niemals** direkt im `frontend/`-Ordner vom Mac-Host. Der `frontend/`-Ordner ist per Volume in den Docker-Container gemountet. Ein `npm install` dort überschreibt die Linux-Binaries mit macOS-Binaries und der Dev-Container funktioniert nicht mehr.
|
||
>
|
||
> Falls das passiert, im Dev-Container reparieren:
|
||
> ```bash
|
||
> cd /workspace/frontend
|
||
> rm -rf node_modules package-lock.json && npm install
|
||
> ```
|
||
|
||
### 4. iOS-Plattform hinzufügen (nur wenn `ios/`-Ordner fehlt)
|
||
|
||
```bash
|
||
cd ~/Sites/thats-me.local/frontend/src-capacitor
|
||
npx cap add ios
|
||
```
|
||
|
||
### 5. CocoaPods für iOS-Projekt initialisieren
|
||
|
||
```bash
|
||
cd ~/Sites/thats-me.local/frontend/src-capacitor/ios/App
|
||
pod install
|
||
```
|
||
|
||
---
|
||
|
||
## Build & Simulator starten (regulärer Workflow)
|
||
|
||
### Schritt 1 – App bauen
|
||
|
||
```bash
|
||
cd ~/Sites/thats-me.local/frontend
|
||
npx quasar build -m capacitor -T ios
|
||
```
|
||
|
||
Das kompiliert den Vue/Quasar-Code und synchronisiert die Assets in das Xcode-Projekt.
|
||
|
||
### Schritt 2 – In Xcode öffnen
|
||
|
||
```bash
|
||
cd src-capacitor
|
||
npx cap open ios
|
||
```
|
||
|
||
### Schritt 3 – Im Simulator ausführen
|
||
|
||
In Xcode:
|
||
|
||
1. Oben links das **Zielgerät** auf einen **Simulator** setzen (z.B. "iPhone 17")
|
||
2. **▶ Play** klicken
|
||
|
||
> **Hinweis:** Für den Simulator wird **kein** Apple Developer Account / Signing benötigt. Signing ist nur für echte Geräte und den App Store erforderlich.
|
||
|
||
---
|
||
|
||
## Nach Code-Änderungen
|
||
|
||
Wenn Änderungen am Vue/Quasar-Code gemacht wurden, immer wieder:
|
||
|
||
```bash
|
||
cd ~/Sites/thats-me.local/frontend
|
||
npx quasar build -m capacitor -T ios
|
||
cd src-capacitor && npx cap open ios
|
||
```
|
||
|
||
In Xcode dann erneut auf ▶ klicken.
|
||
|
||
---
|
||
|
||
## Production Build (App Store)
|
||
|
||
### iOS (App Store / TestFlight)
|
||
|
||
```bash
|
||
npx quasar build -m capacitor -T ios
|
||
cd src-capacitor && npx cap open ios
|
||
```
|
||
|
||
In Xcode:
|
||
|
||
- **Signing & Capabilities** → Apple Developer Account eintragen (kostenpflichtig, $99/Jahr)
|
||
- Zielgerät auf **"Any iOS Device (arm64)"** setzen
|
||
- **Product → Archive → Distribute App**
|
||
|
||
### Android (Google Play)
|
||
|
||
```bash
|
||
npx quasar build -m capacitor -T android
|
||
cd src-capacitor && npx cap open android
|
||
```
|
||
|
||
In Android Studio:
|
||
|
||
- **Build → Generate Signed Bundle / APK**
|
||
- Keystore erstellen/auswählen
|
||
|
||
---
|
||
|
||
## Native APIs / Plugins
|
||
|
||
Capacitor-Plugins ermöglichen Zugriff auf native Funktionen:
|
||
|
||
```bash
|
||
# Beispiele (im src-capacitor Ordner):
|
||
npm install @capacitor/camera
|
||
npm install @capacitor/geolocation
|
||
npm install @capacitor/push-notifications
|
||
|
||
# Nach jedem neuen Plugin:
|
||
npx cap sync
|
||
```
|
||
|
||
---
|
||
|
||
## Git-Hinweise
|
||
|
||
Folgende Ordner sind in `.gitignore` und werden **nicht** commitet:
|
||
|
||
```
|
||
src-capacitor/node_modules/ # Lokal neu installieren mit: npm install
|
||
src-capacitor/www/ # Wird vom Build befüllt
|
||
src-capacitor/ios/ # Lokal generiert mit: npx cap add ios
|
||
src-capacitor/android/ # Lokal generiert mit: npx cap add android
|
||
```
|
||
|
||
**Was commitet wird:**
|
||
|
||
- `src-capacitor/capacitor.config.json` – App-Konfiguration
|
||
- `src-capacitor/package.json` – Capacitor Dependencies
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Fehler | Lösung |
|
||
| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
||
| `spawn pod ENOENT` | `brew install cocoapods` |
|
||
| `xcodebuild requires Xcode` | `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer` |
|
||
| `Cannot find module @rollup/rollup-darwin-arm64` | `rm -rf node_modules package-lock.json && npm install` im `frontend/`-Ordner |
|
||
| `Signing requires a development team` | Für Simulator: ignorieren. Für echtes Gerät: Apple Developer Account in Xcode hinterlegen |
|
||
| `ios platform already exists` | Normal – `npx cap add ios` überspringen, Ordner ist bereits vorhanden |
|
||
| Weißer Bildschirm im Simulator | `npx cap sync` im `src-capacitor`-Ordner, dann neu bauen |
|
||
| Pod-Fehler | `cd src-capacitor/ios/App && pod install --repo-update` |
|