Google Workspace Les modules complémentaires qui étendent Gmail peuvent fournir une interface utilisateur lorsque l'utilisateur lit des messages. Cela permet aux modules complémentairesGoogle Workspace d'automatiser les tâches qui répondent au contenu des messages, telles que l'affichage, la récupération ou l'envoi d'informations supplémentaires concernant le message.
Accéder à l'interface utilisateur des messages du module complémentaire
Il existe deux façons d'afficher l'interface utilisateur des messages d'un module complémentaire. La première consiste à ouvrir un message alors que 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éclenchement 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éclenchement du contexte crée l'interface utilisateur du 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 du 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 la valeur
unconditional
{}
. - Implémentez une fonction de déclencheur contextuel qui crée une interface utilisateur 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'UI de l'utilisateur.
Déclencheurs contextuels
Pour aider les utilisateurs à lire leurs messages,Google Workspace les modules complémentaires 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 de déclenchement*, le déclencheur est exécuté. Un déclencheur déclenché exécute une fonction de déclencheur contextuelle qui crée l'interface utilisateur du module complémentaire et la renvoie pour que Gmail s'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 quelle fonction de déclenchement doit être déclenchée dans quelles conditions. Par exemple, cet extrait 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" } ], ... }, ... } ... }
Fonction de déclenchement du contexte
Chaque déclencheur contextuel doit disposer d'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
du fichier manifeste. Vous implémentez cette fonction pour accepter un argument d'objet d'événement d'action et renvoyez 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éclenchement se basent souvent sur l'ID de message fourni par cet objet d'é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 des messages à 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 du déclencheur peut ensuite agir sur ces données et extraire 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 des ventes dans le corps du message et les organiser pour les afficher dans une fiche.
La fonction de déclenchement doit créer et renvoyer un tableau d'objets Card
compilés. Par exemple, ce qui suit crée un module complémentaire avec une seule fiche qui ne répertorie 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];
}