Cette page a été traduite par l'API Cloud Translation.

Extension de l'interface utilisateur du message

Les modules complémentaires Google Workspace qui étendent Gmail peuvent fournir une interface utilisateur lorsque l'utilisateur lit des messages. Cela permet aux modules complémentaires Google Workspace d'automatiser les tâches en réponse au contenu du message, telles que l'affichage, la récupération ou l'envoi d'informations supplémentaires liées au message.

Accéder à l'interface utilisateur des messages complémentaires

Il existe deux façons d'afficher l'interface utilisateur d'un message dans un module complémentaire. La première méthode consiste à ouvrir un message alors que le module complémentaire est déjà ouvert (par exemple, lorsque la page d'accueil du module complémentaire s'affiche dans la fenêtre de la boîte de réception Gmail). La deuxième méthode consiste à démarrer le module complémentaire tout en consultant un message.

Dans les deux cas, le module complémentaire exécute la fonction de déclencheur contextuel correspondante, définie dans le fichier manifeste du module complémentaire. Le déclencheur s'exécute également si l'utilisateur passe à un autre message alors que le module complémentaire est toujours ouvert. La fonction de déclencheur contextuel crée l'interface utilisateur du message, que Gmail affiche ensuite à l'utilisateur.

Créer un module complémentaire Message

Pour ajouter la fonctionnalité de message à un module complémentaire, procédez comme suit:

Ajoutez les champs appropriés au fichier manifeste du projet de script de module complémentaire, y compris les champs d'application requis pour la fonctionnalité de message. Veillez à ajouter un champ de déclencheur conditionnel au fichier manifeste, avec une valeur unconditional de {}.
Implémentez une fonction de déclencheur contextuel qui crée une UI de message lorsque l'utilisateur sélectionne le module complémentaire dans un message.
Implémentez les fonctions associées nécessaires pour répondre aux interactions de l'utilisateur dans l'interface utilisateur.

Déclencheurs contextuels

Pour aider les utilisateurs à lire des messages, les modules complémentaires Google Workspace peuvent définir un déclencheur contextuel dans leurs fichiers manifestes. Lorsque l'utilisateur ouvre un message Gmail (avec le module complémentaire ouvert) répondant aux critères du déclencheur*, celui-ci s'exécute. Un déclencheur exécuté exécute une fonction de déclencheur contextuel qui construit l'interface utilisateur du module complémentaire et la renvoie pour que Gmail l'affiche. L'utilisateur peut alors commencer à interagir avec lui.

Les déclencheurs contextuels sont définis dans le fichier manifeste du projet de votre module complémentaire. La définition du déclencheur indique à Gmail quelle fonction de déclencheur doit s'exécuter dans quelles conditions. Par exemple, cet extrait de fichier manifeste définit un déclencheur inconditionnel qui appelle la fonction de déclenchement onGmailMessageOpen() lorsqu'un message est ouvert:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Actuellement, le seul type de déclencheur contextuel disponible est unconditional. Il se déclenche pour tous les e-mails, quel que soit leur contenu.

Fonction de déclencheur contextuel

Chaque déclencheur contextuel doit être associé à une fonction de déclencheur qui construit l'interface utilisateur de votre module complémentaire. Spécifiez cette fonction dans le champ onTriggerFunction de votre fichier manifeste. Vous implémentez cette fonction pour accepter un argument d'objet d'événement d'action et renvoyer un seul objet Card ou un tableau d'objets Card.

Lorsqu'un déclencheur contextuel s'exécute pour un message Gmail donné, il appelle cette fonction et lui transmet un objet d'événement d'action. Les fonctions de déclenchement utilisent souvent l'ID de message fourni par cet objet événement pour obtenir le texte du message et d'autres détails à l'aide du service Gmail d'Apps Script. Par exemple, votre fonction de déclencheur peut extraire le contenu du message à l'aide des fonctions suivantes:

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

La fonction de déclencheur peut ensuite agir sur ces données, en extrayant les informations dont elle a besoin pour l'interface. Par exemple, un module complémentaire qui résume les chiffres de vente peut collecter ces chiffres dans le corps du message et les organiser en vue de leur affichage dans une fiche.

La fonction de déclenchement doit créer et renvoyer un tableau d'objets Card compilés. Par exemple, le code suivant crée un module complémentaire avec une seule fiche qui répertorie simplement l'objet et l'expéditeur du message:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }