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

Étendre l'interface utilisateur des messages

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 qui répondent au contenu du message, comme l'affichage, la récupération ou l'envoi d'informations supplémentaires liées au message.

Accéder à l'UI des messages du module complémentaire

Il existe deux façons d'afficher l'UI des messages d'un module complémentaire. La première consiste à ouvrir un message lorsque le module complémentaire est déjà ouvert (par exemple, lorsque vous consultez la page d'accueil du module complémentaire dans la fenêtre de la boîte de réception Gmail). La deuxième consiste à démarrer le module complémentaire lorsque vous consultez 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'UI du message pour ce message, que Gmail affiche ensuite à l'utilisateur.

Créer un module complémentaire de messagerie

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

Ajoutez les champs appropriés au fichier manifeste du projet de script d'extension, y compris les étendues requises 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 avec l'UI.

Déclencheurs contextuels

Pour aider les utilisateurs à lire les 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) qui répond aux critères de déclenchement*, le déclencheur se déclenche. Un déclencheur déclenché exécute une fonction de déclencheur contextuel qui crée l'interface utilisateur du module complémentaire et la renvoie pour que Gmail l'affiche. L'utilisateur peut alors commencer à interagir avec elle.

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 la fonction de déclencheur à exécuter et les conditions à remplir. Par exemple, cet extrait de fichier manifeste définit un déclencheur inconditionnel qui appelle la fonction de déclencheur onGmailMessageOpen() lorsqu'un message est ouvert:

{
  ...
  "addOns": {

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

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

Fonction de déclencheur contextuel

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

Lorsqu'un déclencheur contextuel se déclenche pour un message Gmail donné, il appelle cette fonction et lui transmet un objet d'événement d'action. Les fonctions de déclencheur utilisent souvent l'ID de message fourni par cet objet d'événement pour obtenir le texte du message et d'autres informations à 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 les chiffres de vente dans le corps du message et les organiser pour les afficher dans une fiche.

La fonction de déclencheur 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 ne liste que 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];
  }