geo/app/ANDROID-GUIDE.md

📱 Guide de Développement Android pour GeoSector

🚀 Configuration initiale

Prérequis sur Debian/Ubuntu

# Installer les outils Android de base
sudo apt update
sudo apt install adb fastboot android-tools-adb android-tools-fastboot

# Pour le support MTP (transfert de fichiers)
sudo apt install mtp-tools jmtpfs gvfs-backends

# Vérifier l'installation
adb --version

Configuration du téléphone Android

1. Activer le mode développeur :

   • Aller dans Paramètres > À propos du téléphone
   • Taper 7 fois sur Numéro de build

2. Activer le débogage USB :

   • Aller dans Paramètres > Options pour développeurs
   • Activer Débogage USB
   • Activer Installation via USB (si disponible)

3. Connexion USB :

   • Brancher le téléphone
   • Autoriser le débogage sur le téléphone (popup)
   • Choisir "Toujours autoriser depuis cet ordinateur"

🔍 Commandes ADB essentielles

Vérification de la connexion

# Lister les devices connectés
adb devices

# Voir les infos détaillées du device
adb shell getprop | grep -E "model|version|manufacturer"

# Vérifier si le device est en USB
lsusb | grep -i samsung

Installation et gestion des APK

# Installer un APK
adb install app-release.apk

# Installer en écrasant la version existante
adb install -r app-release.apk

# Installer un APK debug (avec permission de debug)
adb install -t app-debug.apk

# Désinstaller une application
adb uninstall fr.geosector.app2025

# Lister les packages installés
adb shell pm list packages | grep geosector

# Voir le chemin d'installation d'une app
adb shell pm path fr.geosector.app2025

📊 Logs et débogage en temps réel

Voir TOUS les logs du téléphone

# Logs en temps réel (CTRL+C pour arrêter)
adb logcat

# Logs avec filtre sur votre app uniquement
adb logcat | grep -i geosector

# Logs Flutter uniquement (très utile !)
adb logcat | grep -E "flutter|dart"

Logs Flutter spécifiques (RECOMMANDÉ)

# Méthode 1: Via Flutter directement (le plus pratique)
flutter logs

# Méthode 2: Filtrer par tag Flutter
adb logcat -s flutter

# Méthode 3: Logs avec niveau de verbosité
adb logcat "*:E" # Erreurs uniquement
adb logcat "*:W" # Warnings et erreurs
adb logcat "*:I" # Info, warnings et erreurs

Logs avec timestamps et couleurs

# Avec timestamp
adb logcat -v time | grep -i geosector

# Format détaillé avec PID
adb logcat -v threadtime | grep -i geosector

# Sauvegarder les logs dans un fichier
adb logcat -d > logs_android.txt

Nettoyer les logs

# Effacer le buffer de logs
adb logcat -c

# Puis relancer pour voir uniquement les nouveaux logs
adb logcat | grep -i geosector

🐛 Débogage avancé

Lancer l'application depuis ADB

# Démarrer l'application
adb shell monkey -p fr.geosector.app2025 -c android.intent.category.LAUNCHER 1

# Ou avec am (Activity Manager)
adb shell am start -n fr.geosector.app2025/.MainActivity

# Forcer l'arrêt de l'application
adb shell am force-stop fr.geosector.app2025

Capturer des screenshots

# Prendre une capture d'écran
adb shell screencap /sdcard/screenshot.png
adb pull /sdcard/screenshot.png ./screenshot.png

# Enregistrer une vidéo (appuyer CTRL+C pour arrêter)
adb shell screenrecord /sdcard/demo.mp4
adb pull /sdcard/demo.mp4 ./demo.mp4

Informations système

# Voir l'utilisation mémoire
adb shell dumpsys meminfo fr.geosector.app2025

# Voir les permissions de l'app
adb shell dumpsys package fr.geosector.app2025 | grep permission

# Version d'Android
adb shell getprop ro.build.version.release

# Taille de l'écran
adb shell wm size

# Densité de l'écran
adb shell wm density

🔥 Hot Reload avec Flutter

Développement en temps réel

# Lancer l'app en mode debug avec hot reload
flutter run

# Une fois lancé, utiliser ces commandes :
# r - Hot reload (rechargement rapide)
# R - Hot restart (redémarrage complet)
# h - Afficher l'aide
# q - Quitter
# p - Afficher/masquer la grille de construction
# o - Basculer iOS/Android

Lancer sur un device spécifique

# Lister les devices disponibles
flutter devices

# Lancer sur un device spécifique
flutter run -d R3CY409BQBZ  # Remplacer par votre device ID

# Lancer en mode release pour tester les performances
flutter run --release

🏗️ Build et compilation

Générer les APK

# APK debug (non signé, pour tests)
flutter build apk --debug

# APK release (signé, optimisé)
flutter build apk --release

# APK séparés par architecture (plus petits)
flutter build apk --split-per-abi

# App Bundle pour Google Play Store
flutter build appbundle --release

Analyser la taille de l'APK

# Voir la taille détaillée de l'APK
flutter build apk --analyze-size

# Utiliser l'outil APK Analyzer d'Android
java -jar ~/Android/Sdk/tools/bin/apkanalyzer.jar apk summary app-release.apk

🔧 Résolution de problèmes courants

Device non détecté

# Redémarrer le serveur ADB
adb kill-server
adb start-server
adb devices

# Vérifier les règles udev (Linux)
ls -la /etc/udev/rules.d/ | grep android

# Ajouter les permissions utilisateur
sudo usermod -aG plugdev $USER
# Puis se déconnecter/reconnecter

Permissions Android

# Accorder une permission manuellement
adb shell pm grant fr.geosector.app2025 android.permission.ACCESS_FINE_LOCATION

# Révoquer une permission
adb shell pm revoke fr.geosector.app2025 android.permission.ACCESS_FINE_LOCATION

# Lister toutes les permissions
adb shell pm list permissions -g

Problème de signature

# Vérifier la signature de l'APK
jarsigner -verify -verbose -certs app-release.apk

# Voir le certificat
keytool -printcert -jarfile app-release.apk

📦 Transfert de fichiers

Via ADB (recommandé pour dev)

# Envoyer un fichier vers le téléphone
adb push fichier.txt /sdcard/Download/

# Récupérer un fichier du téléphone
adb pull /sdcard/Download/fichier.txt ./

# Lister les fichiers
adb shell ls -la /sdcard/Download/

Via MTP (pour Thunar)

# Monter le téléphone
jmtpfs ~/phone

# Démonter
fusermount -u ~/phone

# Ou redémarrer Thunar
thunar -q && thunar &

🎯 Commandes utiles pour GeoSector

Logs spécifiques à l'application

# Voir les erreurs de l'API
adb logcat | grep -E "ApiService|ApiException"

# Voir les opérations Hive (base de données locale)
adb logcat | grep -i hive

# Voir les erreurs de géolocalisation
adb logcat | grep -E "geolocator|location"

# Tout voir pour GeoSector
adb logcat | grep -E "geosector|flutter" --color=always

Script de déploiement rapide

Créer un fichier deploy-android.sh :

#!/bin/bash
echo "🚀 Déploiement sur Android..."

# Nettoyer et compiler
flutter clean
flutter pub get
flutter build apk --release

# Installer sur le device
adb install -r build/app/outputs/flutter-apk/app-release.apk

# Lancer l'application
adb shell am start -n fr.geosector.app2025/.MainActivity

# Afficher les logs
echo "📊 Logs en temps réel (CTRL+C pour arrêter)..."
adb logcat | grep -E "geosector|flutter" --color=always

Rendre exécutable : chmod +x deploy-android.sh

🏁 Workflow de développement recommandé

1. Brancher le téléphone et vérifier : adb devices
2. Lancer en mode debug : flutter run
3. Modifier le code et appuyer sur r pour hot reload
4. Voir les logs dans un autre terminal : flutter logs
5. Tester la release : flutter run --release
6. Compiler l'APK final : flutter build apk --release
7. Installer : adb install -r app-release.apk

💡 Tips & Tricks

• Performance : Toujours tester en mode --release pour juger les vraies performances
• Logs : Garder un terminal avec flutter logs ouvert en permanence pendant le dev
• Hot Reload : Fonctionne uniquement en mode debug, pas en release
• Wi-Fi Debug : Possible avec adb connect <IP>:5555 après configuration
• Multi-devices : Flutter peut déployer sur plusieurs devices simultanément

---

Guide créé pour le projet GeoSector - Mise à jour : Août 2025