Prise en main d’Apache Cordova

Important

La mise hors service de Visual Studio App Center est prévue pour le 31 mars 2025. Bien que vous puissiez continuer à utiliser Visual Studio App Center jusqu’à sa mise hors service complète, il existe plusieurs alternatives recommandées vers lesquelles vous pouvez envisager la migration.

En savoir plus sur les chronologies et les alternatives de support.

• Android
• iOS
• Extensions iOS
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• Unity
• macOS
• Extensions macOS
• tvOS
• Cordova

Notes

Le support de Cordova Apps a pris fin en avril 2022. Pour plus d’informations, consultez le blog App Center.

Le SDK App Center utilise une architecture modulaire pour vous permettre d’utiliser facilement un, plusieurs ou tous les services App Center dans votre application Apache Cordova.

Dans cet article, vous allez apprendre à ajouter le Kit de développement logiciel (SDK) App Center à vos applications Apache Cordova, puis à configurer les fonctionnalités App Center Analytics et App Center Crash dans une application.

1. Prérequis

Avant de commencer, vérifiez que votre projet d’application Apache Cordova répond aux exigences minimales suivantes :

• Cordova CLI 6.4.0 ou version ultérieure
• cordova-android engine 5.0.0 ou version ultérieure
• cordova-ios engine 4.3.0 ou version ultérieure

Pour déterminer votre version de l’interface CLI Cordova, ouvrez une fenêtre de terminal ou une invite de commandes Windows et exécutez la commande suivante :

cordova -v

Pour déterminer les cordova-android versions et cordova-ios , ouvrez le fichier config.xml du projet, vous trouverez les moteurs de plateforme définis dans les engine éléments présentés ci-dessous :

<engine name="android" spec="~6.2.3" />
<engine name="ios" spec="~4.4.0" />

CocoaPods doit également être installé. Pour cela, exécutez sudo gem install cocoapodspod setup

2. Obtention du secret d’application App Center

Pour que le Kit de développement logiciel (SDK) App Center se connecte à votre projet d’application dans App Center, le SDK a besoin du secret d’application de votre projet App Center. Vous apprendrez plus tard à configurer le Kit de développement logiciel (SDK) Apache Cordova App Center avec cette valeur, mais pour l’instant, voyons où la trouver.

Si vous avez un projet d’application App Center existant, accédez au tableau de bord App Center et ouvrez votre projet. Vous pouvez également utiliser le secret de l’application dans la page Paramètres du projet d’application. Accédez au menu dans le coin supérieur droit de la page, puis sélectionnez Copier le secret de l’application pour copier le secret de l’application dans le Presse-papiers.

Si vous n’avez pas d’application créée dans le tableau de bord App Center, effectuez les étapes suivantes.

1. Inscrivez-vous à un compte App Center ou connectez-vous à un compte App Center existant à l’adresse https://appcenter.ms.
2. Dans le tableau de bord App Center, cliquez sur la liste déroulante Ajouter un nouveau dans le coin supérieur droit de la page. Sélectionnez Ajouter une nouvelle application dans le menu.
3. Entrez un nom pour votre projet d’application, en ajoutant une description facultative si nécessaire.
4. Sélectionnez le système d’exploitation approprié pour votre projet d’application (Android ou iOS uniquement), puis sélectionnez l’option Plateforme Cordova .
5. Cliquez sur le bouton Ajouter une nouvelle application dans le coin inférieur droit de la page.
6. Recherchez le secret de l’application dans la page Paramètres du projet d’application. Accédez au menu dans le coin supérieur droit de la page, puis sélectionnez l’élément Copier le secret de l’application pour copier le secret de l’application dans le Presse-papiers.

3. Ajouter le Kit de développement logiciel (SDK) App Center au projet

Installation du SDK

Pour les projets Apache Cordova, le SDK est distribué via des plug-ins Apache Cordova standard. Ajoutez le Kit de développement logiciel (SDK) App Center à votre projet Cordova en suivant les instructions fournies dans cette section. Commencez par ouvrir une fenêtre Terminal ou une invite de commandes Windows, puis accédez au dossier racine de votre projet Cordova.

Pour ajouter la prise en charge d’App Center Analytics à votre projet, exécutez la commande suivante :

cordova plugin add cordova-plugin-appcenter-analytics

Pour ajouter la prise en charge des incidents App Center à votre projet, exécutez la commande suivante :

cordova plugin add cordova-plugin-appcenter-crashes

Pour ajouter des plug-ins pour toutes les fonctionnalités App Center à votre projet avec une commande, exécutez la commande suivante :

cordova plugin add cordova-plugin-appcenter-analytics cordova-plugin-appcenter-crashes

Notes

Vous devez ajouter cordova-plugin-appcenter-analytics et cordova-plugin-appcenter-crash la plupart des applications qui utilisent App Center ; ils fournissent des informations utiles aux développeurs sans aucune configuration ou codage supplémentaire.

Configuration des plug-ins

Clé secrète de l’application

Vous devez configurer le projet avec le secret d’application de votre projet App Center avant de pouvoir utiliser le SDK App Center dans votre projet Apache Cordova.

Ouvrez le fichier config.xml du projet Apache Cordova ; pour chacun des éléments cibles platform de votre projet Apache Cordova (uniquement Android et iOS aujourd’hui), ajoutez un élément enfant preference au format suivant :

<preference name="APP_SECRET" value="0000-0000-0000-0000-000000000000" />

Dans cet exemple, vous ajoutez un élément avec un name attribut avec la valeur APP_SECRET, et un value attribut avec la valeur indiquée dans l’exemple. Ici, le 0000-0000-0000-0000-000000000000 illustré dans l’exemple est une représentation arbitraire d’un secret d’application de projet App Center. Remplacez le secret d’application indiqué dans l’exemple par le secret d’application réel pour votre projet App Center.

À titre d’exemple complet, pour un projet Apache Cordova qui prend en charge les cibles Android et iOS, vous aurez des définitions de projet d’application distinctes dans App Center, et donc des valeurs de secret d’application différentes pour chaque plateforme cible. La section appropriée du fichier deconfig.xml du projet se présente comme suit :

<platform name="android">
   <preference name="APP_SECRET" value="0000-0000-0000-0000-000000000001" />
</platform>
<platform name="ios">
   <preference name="APP_SECRET" value="0000-0000-0000-0000-000000000002" />
</platform>

Notes

L’exemple n’affiche pas les valeurs réelles de secret d’application ; il s’agit simplement de maquettes. Vous devez récupérer les secrets d’application de votre projet App Center et les utiliser ici. Les secrets d’application sont différents, car vous aurez des secrets uniques pour vos projets d’application Android et iOS dans App Center.

Préférences d’analyse

Si vous utilisez App Center Analytics dans votre application, vous devez effectuer certaines étapes de configuration supplémentaires. Ouvrez le fichier config.xml du projet Apache Cordova dans un éditeur, puis ajoutez un ou plusieurs des éléments suivants preferences au fichier :

• APPCENTER_ANALYTICS_ENABLE_IN_JS - (facultatif, la valeur par défaut est false) Contrôle si Analytics est activé automatiquement. Lorsque false, Analytics est activé par défaut. Lorsque true, l’application doit appeler AppCenter.Analytics.setEnabled(true) (dans son code JavaScript) pour activer Analytics avant d’envoyer des données à App Center. Cette préférence est utile lorsque vous souhaitez demander aux utilisateurs s’ils souhaitent partager des informations analytiques avant de les activer dans l’application. En savoir plus sur l’envoi manuel d’événements utilisateur.

  Exemple :

  <preference name="APPCENTER_ANALYTICS_ENABLE_IN_JS" value="true" />
  

• APPCENTER_CRASHES_ALWAYS_SEND - (facultatif, la valeur par défaut est true) Spécifie si les rapports d’incident sont automatiquement envoyés à App Center lorsque l’application se bloque. Lors de l’envoi automatique de rapports d’incident, chaque incident est signalé, ce qui peut surcharger les équipes d’ingénierie et de support technique. Lorsque vous envoyez des rapports d’incident manuellement (paramètre APPCENTER_CRASHES_ALWAYS_SEND sur false), le code au sein de votre application peut trier les incidents et décider quand les rapports d’incident sont envoyés à App Center, quelles données sont incluses dans les rapports, etc. Cela signifie plus de travail pour le développeur, mais offre également un plus grand contrôle sur la confidentialité de l’utilisateur et vous permet de joindre un message avec un rapport d’incident. En savoir plus sur le traitement des rapports d’incident dans JS.

  Exemple :

  <preference name="APPCENTER_CRASHES_ALWAYS_SEND" value="false" />
  

  Si vous utilisez la sauvegarde automatique pour éviter d’obtenir des informations incorrectes sur les appareils, suivez les étapes suivantes :

Notes

La sauvegarde automatique est automatiquement activée pour les applications qui ciblent Android 6.0 (niveau d’API 23) ou supérieur. 

Notes

Si vous avez déjà un fichier personnalisé avec une règle de sauvegarde, passez à la troisième étape.

a. Créez appcenter_backup_rule.xml fichier dans le dossier res/xml .

<resource-file src="appcenter_backup_rule.xml" target="res/xml/appcenter_backup_rule.xml" />

b. Pour android:fullBackupContent que l’attribut soit ajouté à l’élément <application> dans AndroidManifest.xml fichier, ajoutez les lignes suivantes au fichier config.xml de l’application :

<edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application">
     <application android:fullBackupContent="@xml/appcenter_backup_rule" />
</edit-config>
 ```

c. Add the following backup rules to the **appcenter_backup_rule.xml** file:

```xml
<full-backup-content xmlns:tools="http://schemas.android.com/tools">
   <exclude domain="sharedpref" path="AppCenter.xml"/>
   <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
   <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
   <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
   <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
</full-backup-content>

4. Où aller ensuite ?

Très bien, vous êtes prêt à visualiser les données d’analyse et de plantage collectées automatiquement par le SDK sur le portail. Aucune configuration supplémentaire n’est requise. Consultez les sections Analyse et Incidents pour obtenir des guides d’API et des procédures pas à pas pour découvrir ce qu’App Center peut faire.