Add-ons für Google Workspace, die Gmail erweitern, können eine Benutzeroberfläche bieten, wenn der Nutzer Nachrichten liest. Dadurch können Google Workspace-Add-ons Aufgaben automatisieren, die auf Nachrichteninhalte reagieren, z. B. das Anzeigen, Abrufen oder Senden von zusätzlichen Informationen zur Nachricht.
Auf die Benutzeroberfläche für Add-on-Nachrichten zugreifen
Es gibt zwei Möglichkeiten, die Nachrichten-UI eines Add-ons aufzurufen. Die erste Möglichkeit besteht darin, eine Nachricht zu öffnen, während das Add-on bereits geöffnet ist (z. B. beim Aufrufen der Add-on-Startseite im Gmail-Posteingangsfenster). Die zweite Möglichkeit besteht darin, das Add-on zu starten, während eine Nachricht angezeigt wird.
In beiden Fällen führt das Add-on die entsprechende kontextbezogene Triggerfunktion aus, die im Add-on-Manifest definiert ist. Der Trigger wird auch ausgeführt, wenn der Nutzer zu einer anderen Nachricht wechselt, während das Add-on noch geöffnet ist. Die kontextabhängige Triggerfunktion erstellt die Nachrichten-UI für diese Nachricht, die Gmail dann dem Nutzer anzeigt.
Nachrichten-Add-on erstellen
So fügen Sie einem Add-on Nachrichtenfunktionen hinzu:
- Fügen Sie dem Manifest des Add-on-Skript-Projekts die entsprechenden Felder hinzu, einschließlich der Bereiche, die für die Nachrichtenfunktion erforderlich sind. Fügen Sie dem Manifest ein bedingtes Triggerfeld mit dem
unconditional
-Wert{}
hinzu. - Kontextbezogene Triggerfunktion implementieren, die eine Nachrichten-UI erstellt, wenn der Nutzer das Add-on in einer Nachricht auswählt.
- Zugehörige Funktionen implementieren, die erforderlich sind, um auf die UI-Interaktionen des Nutzers zu reagieren
Kontextbezogene Trigger
Damit Nutzer beim Lesen von Nachrichten unterstützt werden, können Google Workspace-Add-ons in ihren Manifesten einen kontextbasierten Trigger definieren. Der Trigger wird ausgelöst, wenn der Nutzer bei geöffnetem Add-on eine Gmail-Nachricht öffnet, die die Triggerkriterien* erfüllt. Ein ausgelöster Trigger führt eine kontextbezogene Triggerfunktion aus, die die Add-on-Benutzeroberfläche erstellt und sie an Gmail zurückgibt. Dann kann der Nutzer damit interagieren.
Kontextbezogene Trigger werden im Projektmanifest des Add-ons definiert.
Die Triggerdefinition teilt Gmail mit, welche Triggerfunktion unter welchen Bedingungen ausgelöst werden soll. Mit diesem Manifest-Snippet wird beispielsweise ein bedingungsloser Trigger festgelegt, der beim Öffnen einer Nachricht die Triggerfunktion onGmailMessageOpen()
aufruft:
{ ... "addOns": { "common": { ... }, "gmail": { "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ], ... }, ... } ... }
Kontextbezogene Triggerfunktion
Jeder kontextabhängige Trigger muss eine entsprechende Triggerfunktion haben, mit der die Benutzeroberfläche des Add-ons erstellt wird. Sie geben diese Funktion im Feld onTriggerFunction
Ihres Manifests an. Sie implementieren diese Funktion, um ein Argument vom Typ Aktionsereignisobjekt zu akzeptieren und entweder ein einzelnes Card
-Objekt oder ein Array von Card
-Objekten zurückzugeben.
Wenn ein kontextbezogener Trigger für eine bestimmte Gmail-Nachricht ausgelöst wird, wird diese Funktion aufgerufen und ein Aktionsereignisobjekt an sie übergeben. Bei Triggerfunktionen wird häufig die von diesem Ereignisobjekt bereitgestellte Nachrichten-ID verwendet, um den Nachrichtentext und andere Details mit dem Gmail-Dienst von Apps Script abzurufen. Die Triggerfunktion könnte beispielsweise mithilfe der folgenden Funktionen Nachrichteninhalte extrahieren:
// 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();
Die Triggerfunktion kann dann auf diese Daten reagieren und die für die Schnittstelle erforderlichen Informationen extrahieren. Ein Add-on, das Verkaufszahlen zusammenfasst, kann beispielsweise Verkaufszahlen aus dem Nachrichtentext erfassen und zur Anzeige in einer Karte organisieren.
Die Triggerfunktion muss ein Array von erstellten Card
-Objekten erstellen und zurückgeben. Im folgenden Beispiel wird ein Add-on mit einer einzelnen Karte erstellt, auf der nur der Betreff und der Absender der Nachricht aufgeführt sind:
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];
}