Téléchargement et implémentation de tests de bout en bout

Le test des extensions implique l’utilisation de l’API Adobe Experience Platform Launch et/ou d’outils de ligne de commande pour télécharger vos packages d’extension, puis l’utilisation de l’interface utilisateur Platform Launch pour installer votre package d’extension sur une propriété et exercer ses fonctionnalités dans une bibliothèque Platform Launch et la créer.

Les étapes de base pour y parvenir sont les suivantes :

  1. Valider votre extension
  2. Créer une intégration Adobe I/O
  3. Télécharger votre package d’extension
  4. Créer une propriété de développement
  5. Installer votre extension
  6. Créer des ressources pour tester votre extension
  7. Publier vos modifications
  8. Installer Platform Launch sur un site de test
  9. Test

Au fur et à mesure du test (Étape 9 ci-dessus), lorsque vous découvrirez des problèmes qui doivent être résolus, vous exécuterez les tâches suivantes :

  1. Mettre à jour votre code d’extension
  2. Créer un package d’extension
  3. Télécharger votre nouveau package d’extension (votre extension installée fera automatiquement référence à ce nouveau package)
  4. Mettre à jour les ressources en fonction des besoins
  5. Publier à nouveau
  6. Test

Pour les étapes ci-dessous, nous supposons que vous utilisez Mac OS avec Node et npm installés et disponibles.

Valider votre extension

Une fois que votre équipe est satisfaite des performances de votre extension et des résultats qu’elle voit dans l’outil Sandbox, vous devez vous préparer à télécharger votre package d’extension vers Platform Launch.

Avant de télécharger, vérifiez que les champs ou paramètres requis sont présents. Par exemple, il est recommandé de consulter votre manifeste d’extension, votre configuration d’extension, vos vues et vos modules de bibliothèque (au minimum).

Le fichier de logo en est un exemple précis : ajoutez une ligne "iconPath": "example.svg", à votre fichier extension.json et incluez ce fichier image de logo dans votre projet. Il s’agit du chemin relatif à l’icône qui s’affichera pour l’extension dans Platform Launch. Il ne doit pas commencer par une barre oblique. Il doit référencer un fichier SVG avec une extension .svg. Le SVG doit apparaître normalement lorsque son rendu sera carré et peut être mis à l’échelle par notre interface utilisateur. Pour plus d’informations, voir Comment mettre à l’échelle le SVG.

REMARQUE

Pour les extensions publiques, incluez un élément dans votre extension.json avec un lien vers votre liste Exchange. Votre manifeste d’extension doit inclure une entrée de ce type : "exchangeUrl":"https://www.adobeexchange.com/experiencecloud.details.12345.html" pointant vers l’URL de votre liste Exchange.

Créer une intégration Adobe I/O

Pour utiliser l’API ou les outils de ligne de commande, vous devez disposer d’un compte technique auprès d’Adobe I/O. Nous allons créer le compte technique dans la console d’I/O, puis nous utiliserons l’outil de téléchargement pour télécharger le package d’extension.

Pour plus d’informations sur la création d’un compte technique à utiliser avec Platform Launch, reportez-vous au guide Jetons d’accès.

IMPORTANT

Pour créer une intégration dans Adobe I/O, vous devez être un administrateur d’organisation Experience Cloud ou un développeur d’organisation Experience Cloud.

Si vous ne pouvez pas créer d’intégration, vous ne disposez probablement pas des autorisations appropriées et devez communiquer avec l’un de vos administrateurs d’organisation pour accomplir les étapes nécessaires ou pour qu’il vous affecte en tant que développeur afin que vous puissiez le faire vous-même.

Téléchargez votre package d’extension

Une fois vos informations d’identification définies, vous pouvez tester votre package d’extension de bout en bout.

Lorsque vous téléchargez votre package d’extension pour la première fois, il passe à l’état de development. Cela signifie qu’il est uniquement visible avec votre propre société Platform Launch et uniquement avec une propriété Platform Launch qui a été marquée pour le développement d’extensions (plus de détails à ce sujet par la suite).

Pour l’instant, revenez à la ligne de commande du répertoire contenant votre package .zip.

npx @adobe/reactor-uploader

npx vous permet de télécharger et d’exécuter un package npm sans véritablement l’installer sur votre machine. Il s’agit de la manière la plus simple d’exécuter le téléchargeur.

Le téléchargeur vous demandera de saisir plusieurs informations. L’ID de compte technique, la clé d’API et d’autres informations peuvent être récupérés à partir de la console Adobe I/O. Accédez à la page Intégrations dans la console I/O. Sélectionnez l’organisation appropriée dans la liste déroulante, recherchez l’intégration appropriée et sélectionnez View.

  • Quel est le chemin d’accès à votre clé privée ? /path/to/private.key. Il s’agit de l’emplacement où vous avez enregistré votre clé privée à l’étape 2 ci-dessus.
  • Quel est votre ID d’organisation ? Copiez/collez ceci à partir de la page d’aperçu de la console I/O que vous avez laissée ouverte auparavant.
  • Quel est votre ID de compte technique ? Copiez/collez à partir de la console I/O.
  • Quelle est votre clé d’API ? Copiez/collez à partir de la console I/O.
  • Qu’est-ce que le secret client ? Copiez/collez à partir de la console I/O.
  • Quel est le chemin d’accès au package d’extension que vous souhaitez télécharger ? /path/to/extension_package.zip. Si vous appelez le téléchargeur depuis le répertoire contenant votre package .zip, vous pouvez simplement le sélectionner dans la liste au lieu de saisir le chemin d’accès.

Votre package d’extension sera ensuite téléchargé et le téléchargeur vous donnera l’ID du package d’extension.

REMARQUE

Pendant le téléchargement ou l’application de correctifs, les modules d’extension sont placés en attente tandis que le système extrait le module et le déploie de manière asynchrone. Pendant ce processus, vous pouvez interroger l’ID extension_package pour connaître son statut à l’aide de l’API et, dans Platform Launch, une carte d’extension apparaît dans le catalogue portant la mention En attente.

REMARQUE

Si vous prévoyez d’exécuter fréquemment le téléchargeur, intégrer toutes ces informations à chaque fois peut s’avérer fastidieux. Vous pouvez également les transmettre en tant qu’argument à partir de la ligne de commande. Pour plus d’informations, consultez la section Arguments de ligne de commande des documents npm.

Créer une propriété de développement

Lorsque vous vous connectez à Platform Launch, vous voyez d’abord l’écran Propriétés. Une propriété est un conteneur pour les balises que vous souhaitez déployer et elle peut être utilisée sur un ou plusieurs sites.

Vous voyez ici ma propriété « test » mais vous ne verrez aucune propriété sur votre écran la première fois que vous vous connectez. Cliquez sur Nouvelle propriété pour en créer une. Entrez un nom et une URL. Vous voudrez probablement utiliser l’URL de votre site ou page de test où vous testerez votre extension. Ce champ de domaine peut être utilisé par certaines extensions ou par une condition à l’aide de l’extension Core (que nous examinerons plus loin). Veuillez noter que localhost ne fonctionnera pas. Par conséquent, si vous utilisez une URL localhost, utilisez simplement n’importe quelle valeur pour ce test, comme exemple.com.

Comme vous souhaitez utiliser cette propriété pour les tests de développement d’extension, vous devez également développer les Options avancées et vérifier que la case « Configurer pour le développement d’extension » est cochée.

Sélectionnez Enregistrer en bas pour enregistrer votre nouvelle propriété.

Cette action vous ramène à l’écran Propriétés. Cliquez sur le nom de la propriété que vous venez de créer. Il s’agit de l’écran Aperçu d’une propriété. Pas grand chose ne se passe ici, mais il y a des liens vers chaque zone du système, avec les liens de navigation globaux en haut.

Installer votre extension

Pour installer votre extension dans cette propriété, cliquez sur le lien Extensions dans les liens de navigation principaux en haut de la page.

Vous verrez l’extension Core sur cet écran Installé. L’extension Core contient toutes les fonctionnalités de gestion des balises dans Platform Launch. Pour ajouter votre extension, cliquez sur le catalogue :

Celui-ci affiche les icônes de carte pour chaque extension disponible. Si votre extension n’est pas affichée dans le catalogue, veillez à suivre d’abord les étapes ci-dessus dans les sections Configuration de la console d’administration Adobe et Création de votre package d’extension ci-dessus. Votre package d’extension peut également s’afficher comme En attente si Platform Launch n’a pas terminé le traitement initial.

Si vous avez la certitude d’avoir tout fait correctement et que vous ne voyez toujours pas de package d’extension affiché comme En attente ou en Echec dans le catalogue, vous pouvez accéder directement à l’API pour vérifier le statut de votre package d’extension. Pour plus d’informations à ce sujet, consultez Get an ExtensionPackage dans la documentation API.

Si le traitement de votre module d’extension est terminé, la carte comportera un bouton Installer sur lequel vous pourrez cliquer :

Cette action affichera l’écran de configuration que vous avez créé pour votre extension (le cas échéant). Ajoutez les informations nécessaires pour configurer votre extension et cliquez sur Enregistrer en bas de la page. Si votre extension ne comporte pas de configuration, elle sera installée dès que vous cliquerez sur Installer.

Voici un exemple avec l’extension Facebook :

Vous devriez maintenant voir l’écran des extensions Installées avec l’extension Core et votre extension.

Créer des ressources pour tester votre extension

Les extensions offrent de nouvelles fonctionnalités aux utilisateurs dans Platform Launch. Elles s’affichent presque toujours dans les éléments de données ou dans le Créateur de règles. Nous discuterons prochainement de ces deux domaines.

Éléments de données

Éléments de données existent dans Platform Launch pour aider les utilisateurs à conserver les valeurs. Chaque élément de données est un mappage ou un pointeur vers les données sources. Un seul élément de données est une variable dont la valeur peut être mappée à des chaînes de requête, des URL, des valeurs de cookie, des variables JavaScript, etc.

Si nécessaire, les extensions peuvent définir des types d’éléments de données pour que votre extension fonctionne, ou simplement pour faciliter la tâche des utilisateurs. Lorsqu’une extension fournit des types d’éléments de données, ils s’affichent dans une liste déroulante pour les utilisateurs sur l’écran Créer un élément de données :

Lorsqu’un utilisateur sélectionne votre extension dans la liste déroulante Extension, la liste déroulante Type d’élément de données est renseignée avec tous les types d’élément de données fournis par votre extension. L’utilisateur peut ensuite mapper chaque élément de données à sa valeur source. Les éléments de données peuvent ensuite être utilisés lors de la création de règles dans l’Événement de modification des éléments de données ou l’Événement de code personnalisé pour déclencher l’exécution d’une règle. Un élément de données peut également être utilisé dans la condition de l’élément de données ou dans d’autres conditions, exceptions ou actions d’une règle.

Une fois l’élément de données créé (le mappage est configuré), les utilisateurs peuvent référencer les données sources simplement en référençant l’élément de données. Si la source de la valeur change un jour (modification de la conception du site, etc.) les utilisateurs n’ont besoin de mettre à jour le mappage qu’une seule fois dans Platform Launch et tous les éléments de données recevront automatiquement la nouvelle valeur source.

Règles

Sélectionnez le lien Règles dans la barre de navigation supérieure, puis Ajouter la règle :

Tout d’abord, nommez la règle (vous pouvez choisir n’importe quel nom). L’écran Créer une règle est configuré comme une instruction if-then :

Si un événement se produit, que les conditions sont remplies et qu’il n’y a aucune exception, l’action est déclenchée. Ce même flux existe dans les extensions où vous pouvez créer ou exploiter des événements, des conditions, des exceptions, des éléments de données ou des actions.

Pour poursuivre l’exemple Facebook, ajoutons un événement chaque fois qu’une page est chargée sur notre site :

Avec le Type d’événement Window Loaded, chaque fois qu’une page est chargée sur notre site, cette règle est déclenchée. Sélectionnez Enregistrer. Pour cet exemple, ignorons les conditions et les exceptions car nous voulons que cette règle soit déclenchée pour une page de notre site - notre règle On Load « globale » pour ainsi dire.

Sous Actions, cliquez sur Ajouter. Dans cet écran Configuration de l’action, nous pouvons choisir l’extension avec laquelle nous voulons travailler et l’action qui doit se produire lorsque cette règle est déclenchée. Sélectionnez le pixel Facebook sous Extension et Envoyer la page vue sous Type d’action :

Cliquez sur Conserver les modifications en bas de l’écran et sur Enregistrer la règle dans l’écran suivant. Lors du test de votre extension, vous pouvez sélectionner n’importe quel événement, condition, etc. fourni par votre extension dans n’importe quel nombre de règles.

Publier vos modifications

Dans la navigation principale, cliquez sur Publication, puis sur le lien Ajouter une nouvelle bibliothèque :

Une bibliothèque est un ensemble d’instructions qui définit la façon dont les extensions, les éléments de données et les règles interagissent les uns avec les autres, ainsi qu’avec votre site web. Les bibliothèques sont compilées dans des versions. Une bibliothèque peut contenir autant de modifications que l’utilisateur souhaite faire ou tester.

Dans l’écran Créer une nouvelle bibliothèque, ajoutez un nom et choisissez un Environnement. Platform Launch fournit un environnement de développement par défaut nommé Development : sélectionnez-le dans la liste Environnement. Pour l’instant, nous allons ajouter toutes les ressources disponibles ; cliquez sur Ajouter toutes les ressources modifiées.

REMARQUE

Quand vous ajoutez une ressource à une bibliothèque, un instantané de cette ressource est pris à ce moment précis et est ajouté à la bibliothèque. Lorsque vous apportez des modifications à vos ressources ultérieurement (par exemple, suite à des correctifs que vous devez apporter), vous devrez également mettre à jour la bibliothèque pour inclure les dernières modifications apportées à vos ressources. Le bouton Ajouter toutes les ressources modifiées est également utile à cet effet.

Sélectionnez ensuite Enregistrer en bas de la page. Maintenant que toutes nos modifications sont incluses dans cette bibliothèque dev, construisons-la :

Une fois le processus de création terminé, un indicateur de réussite vert doit s’afficher en regard du nom de la bibliothèque :

La bibliothèque Platform Launch est maintenant publiée et en attente d’utilisation. Nous devons maintenant indiquer à notre page de test de rechercher cette bibliothèque afin de pouvoir tester le comportement de l’utilisateur final dans un navigateur.

Installer Platform Launch sur un site de test

Accédons aux instructions d’installation qui sont disponibles dans l’onglet Environnements.

Sur cette page, vous verrez tous les environnements disponibles et vous pourrez en créer davantage. Nous avons publié notre bibliothèque dans l’environnement de développement. Voyons les instructions d’installation de cet environnement en cliquant sur l’icône de boîte dans la colonne Installer de la ligne Développement.

Examinons maintenant les instructions d’installation de l’environnement de développement. Il nous suffit de copier la balise <script> dans la boîte : pour cela, cliquez sur le bouton Copier.

Terminez l’installation en plaçant cette balise <script> unique dans la section <head> de votre document ou modèle de site. Accédez maintenant à votre site de test pour tester le comportement de votre bibliothèque Platform Launch publiée.

Test

Lors de la validation de votre extension sur votre page ou site de test, certaines commandes de console s’avèrent utiles :

  • _satellite.setDebug(true); placera Platform Launch en mode de débogage et consignera des instructions de journalisation utiles dans la console.
  • L’objet _satellite._container contient toutes sortes d’informations utiles sur la bibliothèque déployée, y compris des détails sur la version, les éléments de données, les règles et les extensions inclus.

En fin de compte, votre objectif ici consiste à tester la fonctionnalité de la bibliothèque déployée pour vous assurer que le code que vous avez écrit dans votre package d’extension se comporte comme prévu lorsque Platform Launch l’a compilé dans une bibliothèque.

Lorsque vous découvrez des modifications à apporter à votre package d’extension, le processus d’itération est similaire au processus de développement.

  1. Apporter des modifications au code de votre projet.
  2. Valider les modifications à l’aide de l’outil Sandbox.
  3. Utilisez l’outil Packager pour créer un package .zip.
  4. Utilisez l’outil de téléchargement pour télécharger votre nouveau package .zip. Vous pouvez suivre les mêmes instructions que ci-dessus pour le téléchargement initial, mais vous remarquerez que cette fois, puisqu’il existe déjà un package d’extension de ce nom en mode de développement, celui-ci remplacera l’autre au lieu d’en créer un nouveau. Si vous souhaitez gagner du temps en ne saisissant qu’une seule fois les informations d’identification, vous pouvez consulter la documentation du téléchargeur de réacteurs et transmettre les arguments sur la ligne de commande.
  5. Cette fois, nous pouvons ignorer l’étape d’installation.
  6. Modifier les ressources : si vous avez modifié la configuration de l’un de vos composants d’extension, mettez à jour ces ressources dans l’interface utilisateur de Platform Launch.
  7. Ajoutez vos dernières modifications dans votre bibliothèque et effectuez une nouvelle génération.
  8. Effectuez un nouveau test.

Sur cette page