coach-ios/README.md

Coach Hypnotruck — iOS

Wrapper natif iOS de coach.hypnotruck.ch basé sur Capacitor 8.

Architecture

• Backend : FastAPI + Jinja2 hébergé sur le VPS, accessible via https://coach.hypnotruck.ch
• Coque iOS : Capacitor 8 charge l'URL distante dans un WKWebView
• Plugins natifs : push notifications, local notifications, géolocalisation, HealthKit (Capgo), splash, status bar, haptics

Le code web n'est pas embarqué — l'app pointe vers la prod via server.url dans capacitor.config.ts. Avantage : déploiement web = mise à jour instantanée de l'app sans review Apple.

Bundle ID & nom

• Bundle ID : ch.hypnotruck.coach
• App Store name : Coach Hypnotruck
• Display name : Coach Hypnotruck

Prérequis (sur le Mac mini)

• macOS 13+ (Ventura ou plus récent)
• Xcode 15+ (App Store, ~10 Go)
• Command Line Tools : xcode-select --install
• Homebrew + brew install node cocoapods
• Node 20 LTS (compatible avec Cap 8)
• Compte Apple Developer Program actif (99 USD/an)
• Apple ID dev@hypnotruck.ch connecté dans Xcode → Settings → Accounts

Workflow build

1. Cloner le repo sur le Mac mini

git clone git@gitea:sylvain/coach-ios.git
cd coach-ios
npm install

2. Générer les icônes & splash

npx @capacitor/assets generate --ios

Génère toutes les tailles requises depuis resources/icon.png (1024×1024) et resources/splash.png (2732×2732).

3. Ajouter la plateforme iOS (à faire UNE SEULE FOIS sur le Mac)

npx cap add ios

Cette commande crée le dossier ios/ avec le projet Xcode, qui sera ensuite committé.

4. Sync (à chaque changement de plugins ou config)

npx cap sync ios

5. Ouvrir dans Xcode

npx cap open ios

Dans Xcode :

1. Sélectionner le projet App dans la navigation gauche
2. Onglet Signing & Capabilities :
   • Team : ton équipe Apple Developer
   • Bundle Identifier : ch.hypnotruck.coach
   • Cocher "Automatically manage signing"
3. Ajouter les capabilities requises :
   • HealthKit (lecture FC, pas, calories, VO2max)
   • Push Notifications
   • Background Modes → Remote notifications
4. Onglet Info : ajouter les clés Privacy obligatoires (voir section ci-dessous)

6. Build sur simulateur / device

• Simulateur : choisir un iPhone dans la barre du haut → ⌘R
• Device physique : connecter iPhone par USB, sélectionner, ⌘R (la 1ère fois iOS demande de faire confiance au certificat dev dans Réglages → Général → VPN et gestion des appareils)

7. Upload TestFlight

1. Xcode → Product → Archive
2. Fenêtre Organizer s'ouvre → sélectionner l'archive → Distribute App → App Store Connect → Upload
3. Sur App Store Connect : créer une nouvelle app (1ère fois), section TestFlight → ajouter testeurs (jusqu'à 100 internes sans review, 10 000 externes avec review légère)

Privacy keys requises (Info.plist)

Sans ces clés, iOS crashe à l'usage du plugin. À ajouter dans Xcode → onglet Info → Custom iOS Target Properties :

Clé	Valeur (description affichée à l'utilisateur)
NSHealthShareUsageDescription	"Coach Hypnotruck lit vos données de santé (FC, pas, calories) pour adapter vos séances."
NSHealthUpdateUsageDescription	"Coach Hypnotruck enregistre vos séances dans Santé pour suivre votre progression."
NSLocationWhenInUseUsageDescription	"Coach Hypnotruck utilise votre position pour tracer vos sorties course et VTT."
NSLocationAlwaysAndWhenInUseUsageDescription	"Permet le suivi GPS pendant les sorties même app en arrière-plan."
NSMotionUsageDescription	"Coach Hypnotruck utilise les capteurs de mouvement pour mesurer votre activité."
NSCameraUsageDescription	"Coach Hypnotruck peut utiliser l'appareil photo pour scanner des codes-barres alimentaires."

Anti-rejet App Store (Guideline 4.2)

Apple rejette les apps qui sont juste un wrapper webview sans valeur native. Pour passer review :

• ✅ Push notifications natives (rappel séances) — implémenté côté iOS via @capacitor/push-notifications
• ✅ HealthKit (lecture FC, pas, calories) — implémenté via @capgo/capacitor-health
• ✅ Géolocalisation native pour tracking sorties
• ✅ Local notifications (rappels hors-ligne)
• ✅ Haptics sur actions importantes
• ⏳ À implémenter côté web : appeler ces plugins via JS bridge depuis coach.hypnotruck.ch

Structure repo

coach-ios/
├── capacitor.config.ts       # Config Capacitor (bundle ID, URL, plugins)
├── package.json              # Deps Capacitor + plugins
├── www/                      # Page de bootstrap (chargement, fallback)
│   └── index.html
├── resources/                # Source icônes & splash (1024×1024, 2732×2732)
│   ├── icon.png
│   └── splash.png
├── ios/                      # Projet Xcode (généré par `cap add ios` sur Mac)
└── README.md

Mise à jour de l'app

Type de modif	Action requise
Changement web (templates, CSS, routes)	Aucune — l'app charge la prod en direct
Ajout plugin Capacitor	npm install + npx cap sync ios + nouveau build TestFlight
Changement icône / splash	npx @capacitor/assets generate --ios + sync + nouveau build
Changement bundle ID, version, capabilities	Build + soumission Apple review

TODO Phase 0

• Sur le Mac : npx cap add ios et commit du dossier ios/
• Configurer signing dans Xcode avec Apple ID dev@hypnotruck.ch
• Ajouter les Privacy keys dans Info.plist
• 1er build simulateur pour vérifier que la PWA charge bien
• 1er build device physique (iPhone perso)
• Upload TestFlight pour beta interne
• Préparer screenshots App Store (6.7" iPhone, min 3)
• Privacy policy URL (obligatoire avec HealthKit) — à héberger sur coach.hypnotruck.ch/privacy

Support

• Doc Capacitor
• Capgo Health plugin
• Apple Developer