Google Workspace-Add-ons, die Gmail erweitern, können eine Benutzeroberfläche bereitstellen, wenn der Nutzer Nachrichten liest. So können Google Workspace-Add-ons Aufgaben automatisieren, die auf Nachrichteninhalte reagieren, z. B. zusätzliche Informationen zur Nachricht anzeigen, abrufen oder senden.
Auf die Benutzeroberfläche für Add-on-Nachrichten zugreifen
Es gibt zwei Möglichkeiten, die Benutzeroberfläche für Mitteilungen 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. wenn Sie die Add-on-Startseite im Gmail-Posteingang ansehen. Die zweite Möglichkeit besteht darin, das Add-on zu starten, während Sie eine Nachricht ansehen.
In beiden Fällen wird durch das Add-on die entsprechende kontextbezogene Triggerfunktion ausgeführt, die im Manifest des Add-ons definiert ist. Der Trigger wird auch ausgelöst, wenn der Nutzer zu einer anderen Nachricht wechselt, während das Add-on noch geöffnet ist. Die kontextbezogene Triggerfunktion erstellt die Benutzeroberfläche 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-Skriptprojekts die entsprechenden Felder hinzu, einschließlich der für die Nachrichtenfunktionen erforderlichen Bereichsangaben. Fügen Sie dem Manifest ein Feld für bedingte Trigger mit dem
unconditional-Wert{}hinzu. - Implementieren Sie eine kontextbezogene Triggerfunktion, die eine Nachrichtenschnittstelle erstellt, wenn der Nutzer das Add-on in einer Nachricht auswählt.
- Implementieren Sie die zugehörigen Funktionen, die erforderlich sind, um auf die UI-Interaktionen des Nutzers zu reagieren.
Kontextbezogene Trigger
Um Nutzern beim Lesen von Nachrichten zu helfen, können Google Workspace-Add-ons in ihren Manifesten einen kontextbezogenen Trigger definieren. Wenn der Nutzer eine Gmail-Nachricht öffnet (während das Add-on geöffnet ist), die den Triggerkriterien* entspricht, wird der Trigger ausgelöst. Ein ausgelöster Trigger führt eine kontextbezogene Triggerfunktion aus, die die Add-on-Benutzeroberfläche erstellt und sie zur Anzeige an Gmail zurückgibt. Ab diesem Zeitpunkt kann der Nutzer mit dem Tool interagieren.
Kontextbezogene Trigger werden im Manifest des Add-on-Projekts definiert.
Die Triggerdefinition gibt an, welche Triggerfunktion unter welchen Bedingungen ausgelöst werden soll. In diesem Manifestausschnitt wird beispielsweise ein bedingungsloser Trigger festgelegt, der die Triggerfunktion onGmailMessageOpen() aufruft, wenn eine Nachricht geöffnet wird:
{
...
"addOns": {
"common": {
...
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessageOpen"
}
],
...
},
...
}
...
}Kontextbezogene Triggerfunktion
Jeder kontextbezogene Trigger muss eine entsprechende Triggerfunktion haben, die die Benutzeroberfläche des Add-ons erstellt. Sie geben diese Funktion im Feld onTriggerFunction Ihres Manifests an. Sie implementieren diese Funktion, um ein Aktionsereignisobjekt als Argument 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 übergeben. Häufig verwenden Triggerfunktionen die von diesem Ereignisobjekt bereitgestellte Nachrichten-ID, um den Nachrichtentext und andere Details mit dem Gmail-Dienst von Apps Script abzurufen. Ihre Triggerfunktion könnte beispielsweise mit diesen 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 Informationen extrahieren, die für die Schnittstelle benötigt werden. Ein Add-on, das beispielsweise Verkaufszahlen zusammenfasst, kann Verkaufszahlen aus dem Nachrichtentext erfassen und für die Anzeige auf einer Karte organisieren.
Die Triggerfunktion muss ein Array mit erstellten Card-Objekten erstellen und zurückgeben. Mit dem folgenden Code wird beispielsweise 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];
}