05 — DÉPLOIEMENT MOBILE (APP STORE & PLAY STORE)

Objectif

À la fin de ce fichier :

Les apps React Native (Client + Marchand) se buildent automatiquement via le CI
Les builds de test sont distribuées à l'équipe via TestFlight (iOS) et Firebase App Distribution (Android)
Le process de publication sur App Store et Play Store est documenté et reproductible
Fastlane automatise le signing, le build et l'upload

Pré-requis : fichier 02_cicd_et_services.md complété (l'API staging tourne). Comptes Apple Developer et Google Play Developer créés (pré-requis fichier 00).

Parallélisation : ce fichier peut être exécuté en parallèle des fichiers 03 et 04. Il n'a pas de dépendance sur la sécurisation ni le monitoring — juste sur l'API fonctionnelle.

PHASE 1 — PRÉ-REQUIS MOBILE

1.1 Comptes et accès

Élément	Action	Note
Apple Developer Program	Compte actif ($99/an)	Nécessaire pour TestFlight + App Store
App Store Connect	Créer les 2 apps (Client + Marchand)	Bundle IDs : `com.paywithnex.client` et `com.paywithnex.merchant`
Google Play Console	Compte actif ($25 one-time)	Nécessaire pour Play Store
Google Play Console	Créer les 2 apps	Package names : `com.paywithnex.client` et `com.paywithnex.merchant`
Firebase App Distribution	Activé dans le projet Firebase "nex-app"	Distribution des builds de test Android

1.2 Certificats et clés de signature

iOS — Certificates & Provisioning Profiles

L'agent doit documenter (ou automatiser via Fastlane Match) :

Distribution Certificate : certificat Apple pour signer les builds. Créé dans Apple Developer → Certificates. Un seul certificat par équipe, partagé.
Provisioning Profiles : un profil "Development" (pour TestFlight interne) et un profil "Distribution" (pour l'App Store) par app.
Push Notification Certificate : nécessaire pour Firebase FCM sur iOS. Créé dans Apple Developer → Keys (APNs Key). Un seul key pour toutes les apps.

Recommandation : utiliser Fastlane Match pour gérer les certificats et profiles dans un repo Git privé chiffré. Ça évite les problèmes classiques "le certificat est sur le Mac de Kevin et Kevin est en vacances". Tous les devs et le CI utilisent les mêmes certificats depuis le repo.

Android — Keystore

Upload Key : clé de signature pour uploader sur Google Play. Créée une seule fois avec keytool. Stocker le keystore .jks et son mot de passe dans Doppler (en base64 pour le fichier).
App Signing by Google Play : activé. Google Play re-signe l'app avec sa propre clé. Tu ne donnes que l'upload key.

Important : la perte de l'upload key Android signifie l'impossibilité de publier des mises à jour. Stocker le keystore dans Doppler ET dans un backup sécurisé hors-ligne (clé USB chiffrée dans un coffre physique).

1.3 Configuration des apps

Les apps React Native doivent pointer vers la bonne API selon l'environnement :

Environnement	API URL	Distribution
Development	`http://localhost:3003` ou API staging	Simulateur local
Staging	`https://staging.paywithnex.com`	TestFlight + Firebase App Distribution
Production	`https://api.paywithnex.com`	App Store + Play Store

L'agent doit s'assurer que la configuration d'environnement est gérée proprement dans les apps React Native (via react-native-config, variables d'environnement au build time, ou un mécanisme équivalent). L'URL de l'API ne doit jamais être hardcodée.

PHASE 2 — FASTLANE

Objectif

Fastlane automatise tout ce qui est pénible dans le déploiement mobile : signing, build, upload, screenshots, metadata. Au lieu de faire 47 clics dans Xcode et Google Play Console, tu lances une commande.

Instructions pour l'agent

2.1 Installation

Fastlane doit être installé dans chaque app mobile :

mobile/
├── client/
│   ├── android/
│   │   └── fastlane/
│   │       ├── Fastfile              # Lanes Android
│   │       └── Appfile               # Config (package name, credentials)
│   ├── ios/
│   │   └── fastlane/
│   │       ├── Fastfile              # Lanes iOS
│   │       ├── Appfile               # Config (bundle ID, Apple ID)
│   │       └── Matchfile             # Config Fastlane Match
│   └── ...
├── merchant/
│   └── ...                           # Même structure

2.2 Lanes iOS

L'agent doit créer les lanes suivantes dans le Fastfile iOS :

Lane beta — Build + upload vers TestFlight :

Incrémenter le build number automatiquement
Synchroniser les certificats et profiles via Fastlane Match (mode readonly dans le CI)
Builder l'app en mode Release
Uploader sur TestFlight via upload_to_testflight
Notifier Slack du succès/échec

Lane release — Build + soumission App Store :

Même chose que beta mais upload vers App Store Connect avec upload_to_app_store
Ne soumet PAS automatiquement pour review — juste l'upload. La soumission est manuelle (revue des screenshots, description, etc.)

Lane match_init — Initialisation des certificats (une seule fois) :

Créer les certificats et profiles
Les stocker dans le repo Git chiffré

Recommandations :

Utiliser match(type: "appstore") pour les builds de production et match(type: "development") pour les builds de test.
Configurer le auto-increment du build number basé sur le numéro du pipeline GitLab CI (CI_PIPELINE_IID). Ça garantit un build number unique et toujours croissant.

2.3 Lanes Android

Lane beta — Build + distribution Firebase :

Incrémenter le version code automatiquement
Builder l'APK ou AAB (Android App Bundle) en mode Release
Signer avec l'upload key (keystore depuis Doppler)
Distribuer via Firebase App Distribution
Notifier Slack

Lane release — Build + upload Play Store :

Builder l'AAB (obligatoire pour Play Store, pas APK)
Signer avec l'upload key
Uploader sur Play Store via upload_to_play_store
Track : internal d'abord (test interne), puis production manuellement

Recommandation : toujours builder un AAB (Android App Bundle) pour le Play Store, pas un APK. Google Play optimise l'AAB pour chaque appareil automatiquement.

PHASE 3 — PIPELINE GITLAB CI MOBILE

Objectif

Un pipeline qui build et distribue les apps automatiquement. Les builds de test partent sur TestFlight et Firebase App Distribution à chaque merge sur staging. Les builds de production sont manuelles.

Instructions pour l'agent

3.1 Runners

Les builds iOS nécessitent un Mac (Xcode ne tourne que sur macOS). Deux options :

Option A — GitLab Runner sur un Mac : installer un GitLab Runner sur un Mac de l'équipe ou un Mac mini dédié. Le runner exécute les builds iOS localement.

Option B — Service cloud : utiliser un service comme Codemagic, Bitrise, ou GitHub Actions (qui offre des runners macOS). Ces services sont spécialisés dans le build mobile et éliminent le besoin d'un Mac dédié.

Recommandation : Option B avec Codemagic pour commencer. Codemagic offre 500 minutes/mois gratuites, supporte React Native nativement, et intègre Fastlane. Ça évite de maintenir un Mac Runner. Le .gitlab-ci.yml peut trigger un build Codemagic via webhook ou API.

Pour Android, un runner Linux standard suffit (le SDK Android tourne sur Linux).

3.2 Pipeline structure

yaml

# .gitlab-ci.yml pour les apps mobiles

stages:
  - test
  - build-android
  - build-ios
  - distribute
  - notify

Stage test :

Lancer les tests React Native (Jest)
Lint (ESLint)
Type check (TypeScript)

Stage build-android :

Image : une image Docker avec le SDK Android + Node.js + Fastlane
Décoder le keystore depuis la variable CI (base64)
Lancer fastlane android beta (ou release si branche main)

Stage build-ios :

Runner macOS (ou trigger Codemagic)
Lancer fastlane ios beta (ou release)
Nécessite les certificats Match

Stage distribute :

Android : Firebase App Distribution (déjà fait par Fastlane)
iOS : TestFlight (déjà fait par Fastlane)
Ce stage est surtout pour confirmer et notifier

Stage notify :

Notification Slack avec lien TestFlight et lien Firebase App Distribution

3.3 Variables GitLab CI pour le mobile

Variable	Type	Usage
`ANDROID_KEYSTORE_BASE64`	Variable (masquée)	Keystore Android encodé en base64
`ANDROID_KEYSTORE_PASSWORD`	Variable (masquée)	Mot de passe du keystore
`ANDROID_KEY_ALIAS`	Variable	Alias de la clé dans le keystore
`ANDROID_KEY_PASSWORD`	Variable (masquée)	Mot de passe de la clé
`FIREBASE_APP_ID_CLIENT`	Variable	App ID Firebase pour l'app Client Android
`FIREBASE_APP_ID_MERCHANT`	Variable	App ID Firebase pour l'app Marchand Android
`FIREBASE_CI_TOKEN`	Variable (masquée)	Token Firebase pour App Distribution
`MATCH_GIT_URL`	Variable	URL du repo Git des certificats iOS
`MATCH_PASSWORD`	Variable (masquée)	Mot de passe de déchiffrement Match
`APP_STORE_CONNECT_API_KEY`	File (masquée)	Clé API App Store Connect (.p8)
`GOOGLE_PLAY_JSON_KEY`	File (masquée)	Service account JSON pour Play Store

Recommandation : la clé API App Store Connect (fichier .p8) remplace le login Apple ID dans le CI. C'est la méthode recommandée par Apple pour l'automatisation — pas de 2FA à gérer dans le CI.

PHASE 4 — DISTRIBUTION DE TEST

Objectif

L'équipe et les testeurs reçoivent les builds automatiquement après chaque merge sur staging.

Instructions pour l'agent

4.1 iOS — TestFlight

Les builds uploadées via Fastlane apparaissent automatiquement dans TestFlight
Ajouter les testeurs internes dans App Store Connect → TestFlight → Internal Testing
Les testeurs installent l'app TestFlight sur leur iPhone et reçoivent les nouvelles builds automatiquement
Pas besoin d'UDID ni de provisioning profile spécifique pour les testeurs internes (jusqu'à 100 testeurs)

4.2 Android — Firebase App Distribution

Fastlane upload l'APK via Firebase App Distribution
Ajouter les emails des testeurs dans Firebase Console → App Distribution → Testers
Les testeurs reçoivent un email avec un lien pour installer l'app
Ils doivent activer "Sources inconnues" sur leur appareil Android

Recommandation : créer un groupe de testeurs "internal" dans Firebase App Distribution avec l'équipe dev + CDP. Créer un groupe "beta" pour les testeurs externes (quand vous serez prêts pour le beta testing).

Validation

bash

# Vérifier que les builds sont distribuées
# iOS : dans App Store Connect → TestFlight → builds
# Attendu : dernière build avec le numéro de pipeline GitLab

# Android : dans Firebase Console → App Distribution
# Attendu : dernière build visible avec les testeurs invités

# Les testeurs confirment :
# - App installable
# - App démarre
# - Connexion à l'API staging fonctionne

PHASE 5 — PUBLICATION STORES

Objectif

Processus de publication sur l'App Store et le Play Store. Cette phase est manuelle et intervient quand le produit est prêt pour le lancement.

Instructions pour l'agent

5.1 Préparation commune aux deux stores

Avant de soumettre, préparer :

Élément	Détail	Qui le prépare
Icône de l'app	1024×1024 px (iOS), 512×512 px (Play Store)	Design / CDP
Screenshots	3 à 10 par format d'écran (iPhone 6.5", iPhone 5.5", iPad, Android phone, Android tablet)	Design / CDP
Description courte	30 caractères (Play Store), sous-titre 30 chars (App Store)	CDP
Description longue	Max 4000 caractères	CDP
Mots-clés	100 caractères max (App Store uniquement)	CDP
Politique de confidentialité	URL publique obligatoire	Legal / Compliance
Catégorie	Finance (les deux stores)	CDP
Classification de contenu	Questionnaire à remplir dans Play Console	CDP
Coordonnées	Email de support, site web	CDP

5.2 App Store (iOS)

Process :

Le build est déjà sur App Store Connect via Fastlane (fastlane ios release)
Dans App Store Connect → app → version → sélectionner le build
Remplir les metadata (description, screenshots, notes de version)
Renseigner le questionnaire App Privacy (quelles données l'app collecte)
Soumettre pour review

Délai de review : généralement 24-48h. Peut être plus long pour les apps financières (Apple scrutine les apps de paiement).

Raisons courantes de rejet pour une fintech :

L'app requiert une inscription mais Apple ne peut pas tester sans vrai numéro de téléphone → fournir un compte de test dans les notes du reviewer
L'app mentionne des transactions financières mais n'affiche pas clairement les termes et conditions → s'assurer que les CGU sont accessibles
L'app utilise la caméra ou la localisation sans justification claire → expliquer dans le questionnaire de review pourquoi ces permissions sont nécessaires (KYC pour la caméra par exemple)

Recommandation : fournir un compte de test fonctionnel dans les notes de review Apple avec des instructions claires ("Use phone: +237XXXXXXXXX, OTP: 123456, PIN: 1234"). Cela accélère considérablement la review.

5.3 Play Store (Android)

Process :

Le build AAB est déjà sur Play Console via Fastlane (fastlane android release)
Dans Play Console → app → Release → Production
Remplir les metadata
Remplir le questionnaire Data Safety (quelles données, pourquoi, sont-elles chiffrées, partagées)
Remplir la déclaration de contenu financier (obligatoire pour les apps de paiement)
Soumettre pour review

Parcours de publication Play Store pour les apps fintech :

Google a un processus spécifique pour les apps financières :

L'app doit être déclarée comme "app de services financiers" dans la catégorie
Google peut demander des documents de conformité (licence de l'opérateur, agrément du régulateur)
La première review peut prendre 1-2 semaines pour une app financière

Recommandation : soumettre la première version en mode "Internal testing" d'abord (pas de review), puis promouvoir en "Closed testing" (review légère), puis en "Production" (review complète). Ça permet de valider que le build technique fonctionne pendant que la review se fait.

5.4 Versioning

Convention de version pour les apps :

MAJOR.MINOR.PATCH (BUILD)
Exemple : 1.0.0 (42)

MAJOR : changement incompatible, refonte majeure
MINOR : nouvelle fonctionnalité
PATCH : bugfix
BUILD : auto-incrémenté par le CI (numéro de pipeline)

Le version name (1.0.0) est défini manuellement par l'équipe. Le version code / build number est auto-incrémenté par Fastlane dans le CI.

PHASE 6 — MISES À JOUR POST-LANCEMENT

Objectif

Processus de mise à jour des apps après le lancement initial.

Instructions pour l'agent

6.1 Mises à jour classiques (bugfix, features)

Le processus est simple et répétable :

L'équipe développe sur des feature branches
Merge sur staging → build de test automatique → TestFlight + Firebase App Distribution
L'équipe valide sur les builds de test
Merge sur main → build de production manuelle (1 clic dans GitLab CI)
Fastlane upload sur App Store Connect + Play Console
Soumission manuelle pour review
Review approuvée → l'app est publiée (ou en publication progressive)

6.2 Publication progressive (rollout)

Play Store : Google permet un rollout progressif. Au lieu de publier à 100% des utilisateurs d'un coup :

Jour 1 : rollout à 5% des utilisateurs
Jour 2 : si pas de problème, rollout à 25%
Jour 3 : rollout à 100%

Ça permet de détecter un bug critique avant qu'il n'affecte tout le monde.

App Store : Apple permet aussi un "Phased Release" qui distribue la mise à jour sur 7 jours (1%, 2%, 5%, 10%, 20%, 50%, 100%).

Recommandation : activer le rollout progressif pour toutes les mises à jour en production. C'est un filet de sécurité gratuit.

6.3 Mises à jour urgentes (hotfix)

Pour les bugs critiques qui nécessitent une mise à jour immédiate :

Créer une branche hotfix/xxx depuis main
Fixer le bug
Merge sur main + merge sur staging
Build de production
Soumettre pour review avec le flag "Expedited Review" (App Store) ou rollout à 100% immédiat (Play Store)

Apple offre des reviews accélérées pour les cas urgents (bug critique, faille de sécurité). Ne pas abuser de cette option.

6.4 Forcer la mise à jour

Pour les mises à jour critiques (faille de sécurité, changement d'API breaking), l'app doit pouvoir forcer les utilisateurs à mettre à jour. L'agent doit s'assurer que les apps implémentent un mécanisme de "force update" :

L'app appelle l'API au démarrage pour vérifier la version minimale requise
Si la version de l'app est inférieure à la version minimale, l'app affiche un écran bloquant avec un lien vers le store
La version minimale est configurable côté serveur (dans le service configuration)

CHECKLIST GLOBALE — FIN DU FICHIER 05

Certificats et clés

[ ] Apple Distribution Certificate créé
[ ] Provisioning Profiles créés (Development + Distribution)
[ ] APNs Key créé pour les push notifications iOS
[ ] Fastlane Match configuré (repo Git chiffré avec certificats)
[ ] Keystore Android créé et sauvegardé dans Doppler
[ ] Keystore Android sauvegardé en backup hors-ligne
[ ] App Signing by Google Play activé

Fastlane

[ ] Fastlane installé et configuré pour les 2 apps × 2 plateformes
[ ] Lane beta iOS : build + upload TestFlight
[ ] Lane release iOS : build + upload App Store
[ ] Lane beta Android : build + Firebase App Distribution
[ ] Lane release Android : build AAB + upload Play Store
[ ] Auto-increment du build number configuré

Pipeline CI/CD Mobile

[ ] Runner macOS disponible (Mac local ou Codemagic)
[ ] Pipeline GitLab CI configuré pour les 2 apps
[ ] Variables CI configurées (keystore, Match, App Store Connect API key, Google Play JSON)
[ ] Build automatique sur merge staging
[ ] Build production manuelle disponible

Distribution de test

[ ] TestFlight : testeurs internes ajoutés, builds reçues
[ ] Firebase App Distribution : testeurs ajoutés, builds reçues
[ ] Les apps de test se connectent à l'API staging
[ ] Les push notifications fonctionnent sur les builds de test

Publication stores

[ ] App Store : 2 apps créées dans App Store Connect
[ ] Play Store : 2 apps créées dans Play Console
[ ] Metadata préparées (icône, screenshots, descriptions)
[ ] Politique de confidentialité URL publique
[ ] Compte de test pour les reviewers Apple
[ ] Questionnaires Data Safety / App Privacy remplis

Post-lancement

[ ] Rollout progressif activé (App Store + Play Store)
[ ] Mécanisme de force update implémenté dans les apps
[ ] Processus hotfix documenté

Ce fichier conclut le plan de déploiement. Les 5 fichiers couvrent l'intégralité du chemin : infrastructure → services → sécurité → monitoring → mobile.

05 — DÉPLOIEMENT MOBILE (APP STORE & PLAY STORE) ​

Objectif ​

PHASE 1 — PRÉ-REQUIS MOBILE ​

1.1 Comptes et accès ​

1.2 Certificats et clés de signature ​

iOS — Certificates & Provisioning Profiles ​

Android — Keystore ​

1.3 Configuration des apps ​

PHASE 2 — FASTLANE ​

Objectif ​

Instructions pour l'agent ​

2.1 Installation ​

2.2 Lanes iOS ​

2.3 Lanes Android ​

PHASE 3 — PIPELINE GITLAB CI MOBILE ​

Objectif ​

Instructions pour l'agent ​

3.1 Runners ​

3.2 Pipeline structure ​

3.3 Variables GitLab CI pour le mobile ​

PHASE 4 — DISTRIBUTION DE TEST ​

Objectif ​

Instructions pour l'agent ​

4.1 iOS — TestFlight ​

4.2 Android — Firebase App Distribution ​

Validation ​

PHASE 5 — PUBLICATION STORES ​

Objectif ​

Instructions pour l'agent ​

5.1 Préparation commune aux deux stores ​

5.2 App Store (iOS) ​

5.3 Play Store (Android) ​

5.4 Versioning ​

PHASE 6 — MISES À JOUR POST-LANCEMENT ​

Objectif ​

Instructions pour l'agent ​

6.1 Mises à jour classiques (bugfix, features) ​

6.2 Publication progressive (rollout) ​

6.3 Mises à jour urgentes (hotfix) ​

6.4 Forcer la mise à jour ​

CHECKLIST GLOBALE — FIN DU FICHIER 05 ​

Certificats et clés ​

Fastlane ​

Pipeline CI/CD Mobile ​

Distribution de test ​

Publication stores ​

Post-lancement ​

05 — DÉPLOIEMENT MOBILE (APP STORE & PLAY STORE)

Objectif

PHASE 1 — PRÉ-REQUIS MOBILE

1.1 Comptes et accès

1.2 Certificats et clés de signature

iOS — Certificates & Provisioning Profiles

Android — Keystore

1.3 Configuration des apps

PHASE 2 — FASTLANE

Objectif

Instructions pour l'agent

2.1 Installation

2.2 Lanes iOS

2.3 Lanes Android

PHASE 3 — PIPELINE GITLAB CI MOBILE

Objectif

Instructions pour l'agent

3.1 Runners

3.2 Pipeline structure

3.3 Variables GitLab CI pour le mobile

PHASE 4 — DISTRIBUTION DE TEST

Objectif

Instructions pour l'agent

4.1 iOS — TestFlight

4.2 Android — Firebase App Distribution

Validation

PHASE 5 — PUBLICATION STORES

Objectif

Instructions pour l'agent

5.1 Préparation commune aux deux stores

5.2 App Store (iOS)

5.3 Play Store (Android)

5.4 Versioning

PHASE 6 — MISES À JOUR POST-LANCEMENT

Objectif

Instructions pour l'agent

6.1 Mises à jour classiques (bugfix, features)

6.2 Publication progressive (rollout)

6.3 Mises à jour urgentes (hotfix)

6.4 Forcer la mise à jour

CHECKLIST GLOBALE — FIN DU FICHIER 05

Certificats et clés

Fastlane

Pipeline CI/CD Mobile

Distribution de test

Publication stores

Post-lancement