esup-multi

Arborescence des pages

Configurer Capacitor

Capacitor est le moteur de Ionic qui permet de faire correspondre les méthodes Javascript et les fonctionnalités natives du téléphone (appareil photo, contacts, GPS, ...).
Il remplace aujourd'hui Cordova sur la plupart des projets Ionic.

A la racine du projet se trouve un fichier capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';
 
const config: CapacitorConfig = {
  appId: 'fr.esupportail.mobile.multi',
  appName: 'Esup-Multi',
  webDir: 'www',
};
 
export default config;

Il est important de bien configurer les variables se trouvant dans ce fichier car elles vont permettre d'identifier l'application sur les stores

  • appId : Identifiant unique de l'application
    • = Bundle ID sous iOS
    • = Application ID sous Android
  • appName : Nom de l'application sur les stores
  • webDir : Répertoire contenant l'app Angular compilée

Ajouter le support d'iOS sur le projet

Pour pouvoir créer une app iOS, il faut indiquer à Ionic que l'on souhaite le support natif iOS

npx ionic capacitor add ios

Un nouveau dossier ios/ devrait apparaitre dans votre arborescence, contenant tous les fichiers propres au fonctionnement sur la plateforme.

Cette commande n'est à initier qu'une seule fois sur le projet. Elle n'est plus nécessaire par la suite.

Build des sources Angular

Pour pouvoir générer le package Android ou iOS, il faut au préalable builder l'app Angular.

Le build Angular se fait en 2 étapes :

  • build des modules
  • build de l'app

Pour build tous les modules en 1 commande :

npm run module:build-all

Pour build un module en particulier

npm run module:build {nom_module}

Pour build l'app Angular

npx ng build [--configuration={environment}]

A l'issue de ces builds, votre projet devrait comporter 2 dossiers contenant les sources compilées et minifiées : www/ (= core Angular) et dist/ (= modules)

Pour faciliter cette étape, l'application Multi met à disposition une commande qui permet de lancer le build complet :

npm run build [-- --configuration={environment}]

Build du package iOS

Une fois le build Angular terminé. Il faut utiliser une commande Capacitor qui permet de synchroniser les données des fichiers www/ et dist/ avec le dossier de l'app native ios/

npx ionic capacitor sync ios [--no-build]


Important

Si vous avez passé un environnement à Angular au moment du build, il est impératif d'ajouter l'option --no-build lors de la synchronisation des fichiers.
Sans quoi Ionic relancera le build Angular sans prendre en compte l'environnement en question.

Pour plus d'infos sur l'utilisation des environnements : Configurer plusieurs environnements de développement

Ajouter les autorisations nécessaires pour les fonctionnalités natives

Pour l'utilisation des fonctionnalités natives du périphérique (annuaire de contact, appareil photo, notifications, ...), il est nécessaire de les spécifier dans le fichier de configuration AndroidManifest.xml ou Info.plist. Cela aura pour but de prévenir de leur utilisateur au démarrage de l'application, et permettra à l'utilisateur d'accepter ou non leur utilisation.

Les fonctionnalités natives utilisées sur le projet, qui nécessitent une autorisation sont :

  • L'appareil photo pour le scan des code-barres pour la réservation de matériel
  • L'accès aux photos pour pouvoir stocker temporairement le code-barres scanné pour la réservation de matériel
  • L'annuaire de contacts pour pouvoir ajouter automatiquement un contact issu de l'annuaire de l'établissement
  • La géolocalisation pour l'affichage des POI sur la carte et la gestion des restaurants universitaires à proximité
  • L'utilisation des notifications
  • L'accès à internet

Pour ajouter les autorisations dans le fichier Info.plist, il suffit de coller un couple clé-valeur (<key> / <string>) au sein de la bloc <dict>

Accès à l'appareil photo

<key>NSCameraUsageDescription</key>
<string>L'application a besoin de l'appareil photo pour permettre le scan de code-barre</string>

Accès aux photos

<key>NSPhotoLibraryUsageDescription</key>
<string>L'application a besoin de la bibliothèque de photos pour permettre de stocker temporairement le scan de code-barre</string>

Accès à l'annuaire des contacts

<key>NSContactsUsageDescription</key>
<string>L'application a besoin d'accéder à votre répertoire pour vous permettre d'ajouter un contact depuis la recherche dans l'annuaire</string>

Géolocalisation

<key>NSLocationWhenInUseUsageDescription</key>
<string>L'application a besoin de connaitre votre position afin d'améliorer la présentation des services</string>

Configuration supplémentaire

Pour iOS, il est nécessaire d'ajouter de la configuration supplémentaire dans le fichier Info.plist.

Empêcher l'initialisation automatique de Firebase

<key>FirebaseMessagingAutoInitEnabled</key>
<string>NO</string>

Non utilisation du cryptage non exempté

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

Autoriser l'ouverture d'un lien mailto pour la redirection vers la messagerie

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>mailto</string>
</array>


Pour plus de simplicité, le fichier Info.plist peut aussi être édité depuis Xcode, TARGETS > App > Onglet Info

Générer le splashscreen et les icônes

Pour générer le splashscreen et les icônes de l'application, Multi dispose d'un outil qui se nomme capacitor-assets.

Toute la procédure à suivre est indiquée sur la page suivante : Personnaliser le splashscreen et le logo

La génération de splashscreen et des icônes n'est à réaliser qu'une seule fois. Il n'est pas nécessaire de rejouer la commande à chaque build du client.

Ajouter le support de Firebase pour les notifications push

Pour pouvoir utiliser Firebase sur le projet, vous devez avoir préalablement configuré le projet pour : Configurer Firebase sur le client

Si vous n'avez pas configuré le client pour utiliser Firebase avant le build, mais que vous souhaitez le mettre en place sur le projet, il sera alors nécessaire de rejouer toutes les étapes de build pour prendre en compte les paramètres.

Pour finaliser l'utilisation de Firebase sur votre client Android il ne reste alors plus qu'à copier le fichier GoogleService-Info.plist dans le répertoire ios/App/App

Cette procédure peut être automatisée en fonction de l'environnement à utiliser en utilisant l'outil Trapeze décrit ci-dessous

Le fichier GoogleService-Info.plist doit impérativement avoir été ajouté manuellement au projet iOS depuis XCode pour qu'il soit référencé sur le projet dans l'IDE.
Une fois le fichier ajouté depuis XCode, il ne sera pas nécessaire de le remplacer par la suite depuis l'IDE. Il suffira d'utiliser Trapeze pour le remplacer à chaud sur le projet.

Pour que les notifications push fonctionnent sur iOS, il est impératif de rajouter la capability 'Push Notifications' dans XCode.

Il est nécessaire d'ajouter également la capability 'Background Modes' et cocher la checkbox 'Remote notifications'


Utiliser Trapeze pour faciliter les modifications du package iOS

Trapeze est un outil qui permet de modifier de l'information à chaud directement dans les fichiers des applications natives, sans avoir à rebuilder les dossiers avec ionic cap sync

Dans le projet Multi, il est principalement utilisé pour modifier les numéros de version et build du projet, et copier les fichier Firebase aux bons endroits.

vars:
  BUNDLE_ID:
    default: fr.esupportail.mobile.multi
  PACKAGE_NAME:
    default: fr.esupportail.mobile.multi
  VERSION_NAME:
    default: "1.0.0"
  BUILD_NUMBER:
    default: "000001"

platforms:
  android:
    packageName: $PACKAGE_NAME
    versionName: $VERSION_NAME
    versionCode: $BUILD_NUMBER
    copy:
      - src: ../src/environments/firebase/android/google-services-prod.json
        dest: app/google-services.json

  ios:
    bundleId: $BUNDLE_ID
    version: $VERSION_NAME
    buildNumber: $BUILD_NUMBER
    copy:
      - src: ../../src/environments/firebase/ios/GoogleService-Info-prod.plist
        dest: App/GoogleService-Info.plist

Dans cette conf, il est possible de passer en variable d'environnement :

  • Le bundle_id (iOS)
  • Le package_name (Android)
  • Le numéro de version
  • Le numéro de build

Le script se charge ensuite, suivant la plateforme, d'aller modifier ces informations dans le code respectif des app natives, et d'y coller les fichiers Firebase spécifiés

Pour exécuter la commande Trapeze :

[VAR_ENV_1="value" VAR_ENV_2="value"] npx trapeze run trapeze-config.yml

Pour configurer Trapeze sur plusieurs environnements : Configurer plusieurs environnements de développement#EnvironnementsTrapeze

L'outil Trapeze permet de modifier plus finement les configurations des app natives, comme ajouter automatiquement les droits nécessaires au build ou mettre à jour les fichiers de conf AndroidManifest.xml et Infos.plist.
Pour plus d'informations sur la configuration de Trapeze : https://trapeze.dev/docs/Operations/getting-started

Ouvrir le projet sous XCode pour tester l'application

Les étapes suivantes nécessitent impérativement une machine fonctionnant sous MacOS

Une fois le projet iOS buildé et configuré, il ne reste plus qu'à l'ouvrir sous XCode. Pour cela, exécutez la commande :

npx ionic capacitor open ios

L'IDE devrait alors s'ouvrir, affichant l'arborescence du projet.

Vous pouvez désormais testé le projet iOS en sélectionnant le périphérique souhaité (émulateur ou device connecté) dans le menu déroulant en haut

Puis en cliquant sur le bouton (Start the active scheme)

Préparer l'App Bundle pour la diffusion sur l'App Store

A venir

Infos générale du projet

Configurer les certificats

Builder le package

Publier sur l'App Store

Publier l'application sur les stores

Todo Checklist de re-déploiement

Vous trouverez ci-dessous la checklist des actions à effectuer pour build ou rebuild l'app native et la publier sur les stores.

En gris, les actions à n'effectuer qu'une seule fois.
Entre parenthèses, les actions facultatives.
Les autres actions sont à faire à chaque nouvelle release. 

  • Configurer Capacitor en éditant le fichier capacitor.config.ts
  • Ajouter le support d'iOS sur le projet
    npx ionic capacitor add ios

  • Build les sources d'Angular avec les modules
    npm run build [-- --configuration={environment}]

  • Synchronisation des sources Angular avec les packages natifs iOS
    npx ionic capacitor sync ios [--no-build]

  • Ajouter les autorisations pour les fonctionnalités natives et la configuration dans le fichier Info.plist
  • Générer le Splashscreen et les icônes de l'application avec l'outil capacitor-assets
  • Exécuter la configuration Trapeze pour mettre à jour les numéros de version et build + (copie des fichiers de configuration Firebase)
  • Ouvrir le projet dans XCode
    npx ionic capacitor open ios

  • (Ajouter la configuration Firebase en collant le fichier GoogleService-Info.plist dans le dossier ios/App/App/ depuis Xcode)
  • Vérifier que l'on retrouve bien les autorisations nécessaires dans l'onglet App > Info
  • Vérifier que l'on retrouve bien les bonnes valeurs pour les attributs Bundle Identifier, Version et Build dans l'onglet App > General
  • Configurer les certificats pour la signature du bundle
  • Générer le Bundle signé : menu > Product > Archive
  • Valider l'application
  • Distribuer l'application sur TestFlight
  • Passer l'application en production sur l'App Store
  • Aucune étiquette