Convertir un projet Cordova en projet PhoneGap

PhoneGap est une infrastructure open source qui permet de créer rapidement des applications mobiles interplateformes en HTML5, JavaScript et CSS. Adobe PhoneGap Build est un service cloud qui vous permet de créer rapidement des applications mobiles et de les compiler facilement sans Kits de développement logiciel (SDK), ni compilateurs, ni matériel. Cet article décrit comment convertir un projet Apache Cordova créé à l'aide de Visual Studio en projet PhoneGap et comment utiliser le service cloud PhoneGap Build.

L'une des principales différences entre un projet Visual Studio et le projet PhoneGap réside dans la définition de l'application dans le fichier de configuration (config.xml). Vous devez effectuer les tâches suivantes pour convertir votre projet Visual Studio en projet PhoneGap :

1. Créer le projet Cordova à partir de votre projet Visual Studio

2. Créer la structure de projet PhoneGap

3. Mettre à jour le fichier config.xml

4. Télécharger vers une build dans le cloud

5. Signer le code et configurer l'application

Créer un projet Cordova à partir de votre projet Visual Studio

Nous allons commencer par examiner un exemple de structure de projet pour un projet créé à l'aide de Visual Studio Tools for Apache Cordova.

Pour générer correctement une build, le service cloud PhoneGap Build a uniquement besoin des ressources web de votre application (HTML, CSS, images, fichiers .js, etc.). Il est fort probable que PhoneGap Build ne parvienne pas à compiler votre application si des fichiers natifs sont téléchargés (.h, .m, .java, etc.). Le moyen le plus simple d'obtenir les ressources web de votre application consiste à créer votre projet Visual Studio, ce qui entraîne la création d'un projet Cordova CLI dans le dossier bld/Debug, comme indiqué ci-dessous. Le dossier www du projet Cordova CLI héberge toutes les ressources web utilisées dans votre application, comme indiqué ci-dessous.

Une fois le dossier www généré, vous pouvez créer votre projet PhoneGap Build. Nous vous recommandons de créer un dossier (en dehors de l'emplacement de votre projet Visual Studio) pour héberger votre projet PhoneGap, puis de copier le dossier www du projet Cordova CLI situé à l'emplacement bld/debug vers le nouvel emplacement.

Créer la structure de projet PhoneGap

Quand vous définissez la structure du projet PhoneGap, vérifiez que les fichiers config.xml et index.html se trouvent au niveau supérieur de la structure de dossiers de votre application. Sinon, vous pouvez structurer votre application en fonction de vos besoins. Copiez le fichier config.xml situé dans le dossier bld/debug vers le dossier www du projet PhoneGap Build. Copiez aussi les ressources natives du projet Cordova CLI (bld\Debug\res\icons et bld\debug\res\screens) à la racine de votre projet PhoneGap Build.

Une fois tous les fichiers et dossiers copiés, le projet PhoneGap Build doit ressembler à ceci.

Étant donné que votre application peut contenir des fichiers ou des dossiers qui ne sont pas requis dans votre application empaquetée finale (notamment des écrans de démarrage inutilisés, des packages Bower, des artefacts Grunt, des fichiers .less non compilés, etc.), PhoneGap Build prend en charge un fichier spécial appelé .pgbomit.

.pgbomit est un fichier que vous pouvez créer et ajouter à un dossier pour demander à PhoneGap Build d'exclure le dossier comme source de fichiers d'application natifs. (Toutefois, vous pouvez utiliser ce dossier pour stocker les fichiers nécessaires au cours du processus de build PhoneGap, et ce jusqu'à l'étape de compilation.) Par exemple, vous pouvez placer .pgbomit dans le dossier contenant les icônes et les écrans de démarrage. Placez .pgbomit dans le dossier www/res de votre projet PhoneGap Build. En conséquence, aucun des fichiers et dossiers contenus dans www/res ne seront inclus dans le package d'application binaire, sauf ceux copiés et utilisés pour les icônes et les écrans de démarrage pour une plateforme spécifique. L'illustration suivante montre le fichier .pgbomit dans le dossier www/res.

Étant donné que PhoneGap Build ne prend pas en charge le dossier merges du projet Cordova CLI par défaut, vous devez copier le contenu spécifique à la plateforme situé dans le dossier merges de votre projet Cordova CLI vers le dossier www du projet PhoneGap Build.

Mettre à jour le fichier Config.xml

PhoneGap Build prend en charge un fichier XML de configuration, config.xml, qui est très différent de celui généré par le projet Visual Studio. Ce fichier de configuration vous permet de modifier des éléments tels que le titre, les icônes, les écrans de démarrage et d'autres propriétés de l'application.

Commencez par supprimer l'espace de noms VS et par ajouter l'espace de noms PhoneGap au fichier config.xml. Le résultat est indiqué ici.

<widget xmlns:cdv="http://cordova.apache.org/ns/1.0"
  id="io.cordova.appb64ec64666e9432a9caf5f01009feb88"
  version="1.0.0.0"
  xmlns:gap="http://phonegap.com/ns/1.0"
  xmlns="http://www.w3.org/ns/widgets">
<name>SlidePuzzle</name>

Icônes

L'icône par défaut doit être nommée icon.png et doit résider à la racine de votre dossier d'application. Sauf indication contraire dans le fichier config.xml, chaque plateforme tente d'utiliser le fichier icon.png par défaut pendant la compilation.

<icon src="icon.png" />

Si vous souhaitez utiliser des icônes spécifiques pour la plateforme Android, les entrées suivantes illustrent comment mettre à jour le fichier config.xml en fonction du contenu du dossier res\icons\android dans le projet PhoneGap Build créé précédemment.

<icon gap:platform="android" gap:qualifier="ldpi"
    src="www/res/icons/android/icon-36-ldpi.png" />
<icon gap:platform="android" gap:qualifier="mdpi"
    src="www/res/icons/android/icon-48-mdpi.png" />
<icon gap:platform="android" gap:qualifier="hdpi"
    src="www/res/icons/android/icon-72-hdpi.png" />
<icon gap:platform="android" gap:qualifier="xhdpi"
    src="www/res/icons/android/icon-96-xhdpi.png" />

Pour plus d'informations sur la spécification d'éléments d'icône dans le fichier config.xml, consultez cet article.

Écrans de démarrage

Le fichier config.xml peut comprendre entre zéro et plusieurs éléments d'écran de démarrage. L'élément d'écran de démarrage peut avoir des attributs src, gap:platform, width et height, au même titre que l'élément <icon>. Comme les fichiers d'icône, enregistrez les fichiers d'écran de démarrage en tant qu'images PNG. Sauf indication contraire dans le fichier config.xml, chaque plateforme utilise le fichier splash.png par défaut pendant la compilation. Si vous ne fournissez pas l'attribut gap:platform, l'image par défaut est copiée sur toutes les plateformes, ce qui augmente la taille de chaque package d'application.

L'écran de démarrage par défaut doit être nommé splash.png et doit résider à la racine de votre dossier d'application.

<gap:splash src="splash.png" /> 

Si vous souhaitez utiliser des écrans de démarrage spécifiques pour la plateforme Android, les entrées suivantes illustrent comment mettre à jour le fichier config.xml en fonction du contenu du dossier res\screens\android dans le projet PhoneGap Build.

<gap:splash gap:platform="android" gap:qualifier="port-ldpi" 
    src="www/res/screens/android/screen-ldpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-mdpi" 
    src="www/res/screens/android/screen-mdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-hdpi" 
    src="www/res/screens/android/screen-hdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-xhdpi" 
    src="www/res/screens/android/screen-xhdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="land-ldpi" 
    src="www/res/screens/android/screen-ldpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-mdpi" 
    src="www/res/screens/android/screen-mdpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-hdpi" 
    src="www/res/screens/android/screen-hdpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-xhdpi" 
    src="www/res/screens/android/screen-xhdpi-landscape.png" />

Pour plus d'informations sur la spécification d'éléments d'écran de démarrage dans le fichier config.xml, consultez cet article.

Plug-ins

Pour étendre l'accès aux fonctionnalités de plateforme natives exposées par le conteneur d'applications natives PhoneGap, PhoneGap Build prend en charge une liste verte de plug-ins PhoneGap. Pour obtenir la liste des plug-ins pris en charge, consultez Plug-ins. Si vous incluez des plug-ins qui ne figurent pas dans la liste verte d'Adobe, la build échoue. Pour importer un plug-in dans votre projet PhoneGap Build, vous devez ajouter l'élément <gap:plugin> approprié au fichier config.xml. Si vous omettez l'attribut de version du plug-in, l'application est toujours créée à l'aide de la dernière version du plug-in.

Voici la façon la plus simple d'utiliser un plug-in avec version.

<gap:plugin name="com.phonegap.plugins.example" version="2.2.1" />

Étant donné que Visual Studio émet l'élément <vs:plugin> dans le fichier config.xml pour chaque plug-in ajouté, vous devez remplacer ces éléments par des éléments <gap:plugin>. Dans notre exemple de projet, nous utilisons deux plug-ins et deux lignes correspondantes dans le fichier config.xml.

<vs:plugin name="org.apache.cordova.device-motion" version="0.2.10" />
<vs:plugin name="org.apache.cordova.camera" version="0.3.2" /> 

Dans le projet PhoneGap Build, ces lignes doivent être remplacées par :

<gap:plugin name="org.apache.cordova.device-motion" version="0.2.10" />
<gap:plugin name="org.apache.cordova.camera" version="0.3.2" /> 

Pour plus d'informations sur la modification des plug-ins, consultez cet article.

Télécharger votre projet vers PhoneGap

Après avoir apporté toutes les modifications requises, vous pouvez télécharger votre application vers le service de build PhoneGap. Tout d'abord, créez un compte auprès du service de build PhoneGap. Ensuite, connectez-vous à votre compte à l'adresse https://build.phonegap.com/apps pour soumettre votre application. Vous pouvez soumettre votre application à partir d'un référentiel GIT, ou vous pouvez télécharger un fichier ZIP local. Dans cet exemple, nous allons télécharger un fichier ZIP local qui contient le dossier www zippé. Une fois le fichier ZIP téléchargé, votre application est prête à être créée.

Quand vous cliquez sur le bouton Ready to Build, le service de build PhoneGap crée votre application pour les plateformes que vous avez définies dans le fichier config.xml. Comme nous n'avons pas défini de plateforme particulière, le service crée l'application pour les trois plateformes (iOS, Android et Windows). Une fois la build terminée, les résultats apparaissent.

Signer le code et configurer votre application

Étant donné que nous utilisons un service de build dans le cloud, nous devons définir les certificats de signature de code et de configuration pour prendre en charge la création de packages de publication/distribution signés. Pour iOS, vous pouvez fournir le certificat de signature de code et le profil de configuration mobile ici :

Pour générer un package APK de distribution pour Android prêt à envoyer au magasin, le service de build PhoneGap vous permet de fournir les informations relatives au magasin de clés et les mots de passe correspondants ici :

Pour Android, nous allons utiliser un magasin de clés existant que nous avons créé précédemment (ou vous pouvez en créer un en suivant la procédure décrite dans ce guide), puis recréer l'application. À présent, le service de build crée un package de distribution entièrement signé qui peut être téléchargé à des fins de publication vers le magasin ou installé sur un appareil attaché.

Nous espérons que cet article vous aidera à convertir votre projet Visual Studio Cordova en projet PhoneGap Build et qu'il vous permettra de créer rapidement des applications pour iOS, Android ou Windows à l'aide du service de build PhoneGap.

Si vous avez déjà installé Visual Studio Tools for Apache Cordova et que vous l'utilisez activement, nous vous en remercions. Dans le cas contraire, visitez cette page pour obtenir les outils.