Extension de l'interface utilisateur de Compose avec des actions de rédaction

En plus de fournir une interface basée sur des cartes lorsqu'un utilisateur lit un message Gmail, les modules complémentaires Google Workspace qui étendent Gmail peuvent fournir une autre interface lorsque l'utilisateur rédige de nouveaux messages ou répond à des messages existants. Cela permet aux modules complémentaires Google Workspace d'automatiser la tâche de rédaction d'e-mails pour l'utilisateur.

Accéder à l'UI Compose du module complémentaire

Il existe deux façons d'afficher l'UI Compose d'un module complémentaire. La première consiste à commencer à rédiger un brouillon ou une réponse alors que le module complémentaire est déjà ouvert. La deuxième consiste à démarrer le module complémentaire lors de la rédaction d'un brouillon.

Dans les deux cas, le module complémentaire exécute la fonction de déclenchement de composition correspondante, définie dans le manifeste du module complémentaire. La fonction de déclencheur Compose crée l'UI Compose pour cette action Compose, que Gmail affiche ensuite à l'utilisateur.

Créer un module complémentaire Compose

Pour ajouter la fonctionnalité Compose à un module complémentaire, suivez ces étapes générales :

1. Ajoutez le champ gmail.composeTrigger au fichier manifeste du projet de script du module complémentaire et mettez à jour les scopes du fichier manifeste pour inclure ceux requis pour les actions de rédaction.
2. Implémentez une fonction de déclencheur Compose qui crée une UI Compose lorsque le déclencheur est activé. Les fonctions de déclenchement Compose renvoient un seul objet Card ou un tableau d'objets Card qui composent l'UI Compose pour l'action de rédaction.
3. Implémentez les fonctions de rappel associées nécessaires pour réagir aux interactions de l'utilisateur avec l'UI Compose. Ces fonctions ne sont pas l'action de composition elle-même (qui ne fait qu'apparaître l'UI de composition). Il s'agit plutôt des fonctions individuelles qui régissent ce qui se passe lorsque différents éléments de l'UI de composition sont sélectionnés. Par exemple, une fiche d'interface utilisateur contenant un bouton est généralement associée à une fonction de rappel qui s'exécute lorsqu'un utilisateur clique sur ce bouton. La fonction de rappel pour les widgets qui mettent à jour le contenu du brouillon de message doit renvoyer un objet UpdateDraftActionResponse.

Composer une fonction de déclencheur

L'interface utilisateur Compose d'un module complémentaire est créée de la même manière que l'interface utilisateur de message du module complémentaire, à l'aide du service Card d'Apps Script pour construire des fiches et les remplir avec des widgets.

Vous devez implémenter gmail.composeTrigger.selectActions[].runFunction que vous définissez dans votre fichier manifeste. La fonction de déclencheur Compose doit renvoyer un seul objet Card ou un tableau d'objets Card qui composent l'UI Compose pour cette action. Ces fonctions sont très similaires aux fonctions de déclenchement contextuel et doivent créer des fiches de la même manière.

Avertissement : Pour des raisons de sécurité, les modules complémentaires ne peuvent pas modifier silencieusement les autorisations d'accès aux fichiers Google Workspace ou tiers. Par exemple, un module complémentaire ne peut pas ajouter silencieusement des destinataires d'e-mails à l'ensemble des comptes pouvant afficher un fichier Dropbox. Le module complémentaire doit plutôt informer les utilisateurs que l'autorisation est en train d'être modifiée. Les modules complémentaires qui n'informent pas les utilisateurs de ces modifications ne peuvent pas passer la vérification des modules complémentaires.

Composer des objets d'événement déclencheur

Lorsqu'une action de composition est sélectionnée, elle exécute la fonction de déclencheur de composition correspondante et lui transmet un objet d'événement en tant que paramètre. L'objet d'événement peut transmettre des informations sur le contexte du module complémentaire et le brouillon en cours de rédaction à la fonction de déclencheur.

Consultez Structure de l'objet Event pour en savoir plus sur la façon dont les informations sont organisées dans l'objet Event. Les informations contenues dans l'objet d'événement sont partiellement contrôlées par la valeur du champ de fichier manifeste gmail.composeTrigger.draftAccess :

• Si le champ de fichier manifeste gmail.composeTrigger.draftAccess est défini sur NONE ou n'est pas inclus, l'objet d'événement ne contient que des informations minimales.

• Si gmail.composeTrigger.draftAccess est défini sur METADATA, l'objet d'événement transmis à la fonction de déclencheur de rédaction est renseigné avec des listes de destinataires de l'e-mail en cours de rédaction.

Remarque : Pour utiliser l'accès aux brouillons METADATA, le fichier manifeste du module complémentaire doit inclure le champ d'application Gmail https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

Insérer du contenu dans des brouillons actifs

En règle générale, l'UI de composition d'un module complémentaire Google Workspace fournit à l'utilisateur les options et les commandes qui l'aident à composer un message. Pour ces cas d'utilisation, une fois que l'utilisateur a effectué des sélections dans l'UI, le module complémentaire interprète les sélections et met à jour le brouillon d'e-mail en cours en conséquence.

Pour faciliter la mise à jour de l'e-mail brouillon actuel, le service de cartes a été étendu avec les classes suivantes :

• ContentType : énumération qui définit s'il faut ajouter du contenu HTML modifiable, du contenu HTML immuable (que les utilisateurs Gmail ne peuvent pas modifier) ou du contenu en texte brut.
• UpdateDraftActionResponse : représente une réponse à une action qui met à jour l'e-mail en cours de rédaction.
• UpdateDraftActionResponseBuilder : compilateur pour les objets UpdateDraftActionResponse.
• UpdateDraftBodyAction : représente une action qui met à jour le corps de l'e-mail brouillon actuel.
• UpdateDraftBodyType : énumération qui définit la façon dont le corps est modifié.
• UpdateDraftSubjectAction : représente une action qui met à jour le champ "Objet" de l'e-mail en cours de rédaction.
• UpdateDraftToRecipientsAction : représente une action qui met à jour les destinataires "À" de l'e-mail en cours de rédaction.
• UpdateDraftCcRecipientsAction : représente une action qui met à jour les destinataires en copie de l'e-mail en cours de rédaction.
• UpdateDraftBccRecipientsAction : représente une action qui met à jour les destinataires en copie cachée de l'e-mail en cours de rédaction.

En général, l'UI Compose d'un module complémentaire inclut un widget "Enregistrer" ou "Insérer" sur lequel un utilisateur peut cliquer pour indiquer qu'il a terminé de faire des sélections dans l'UI et qu'il souhaite que ses choix soient ajoutés à l'e-mail qu'il est en train de rédiger. Pour ajouter cette interactivité, le widget doit être associé à un objet Action qui indique au module complémentaire d'exécuter une fonction de rappel spécifique lorsque l'utilisateur clique sur le widget. Vous devez implémenter ces fonctions de rappel. Chaque fonction de rappel doit renvoyer un objet UpdateDraftActionResponse créé qui détaille les modifications à apporter à l'e-mail brouillon actuel.

Exemple 1

L'extrait de code suivant montre comment créer une interface utilisateur Compose qui met à jour l'objet, ainsi que les destinataires "À", "Cc" et "Cci" de l'e-mail en cours de rédaction.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

Exemple 2

L'extrait de code suivant montre comment créer une interface utilisateur Compose qui insère des images dans l'e-mail en cours.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }