Nachrichten-UI erweitern

Google Workspace-Add-ons, die Gmail erweitern, können eine Benutzeroberfläche bereitstellen, wenn der Nutzer Nachrichten liest. So können Add-ons Aufgaben automatisieren, die auf Nachrichteninhalte reagieren, z. B. zusätzliche Informationen zur Nachricht anzeigen, abrufen oder senden.

Benutzeroberfläche für Nachrichten von Google Workspace-Add-ons aufrufen

Es gibt zwei Möglichkeiten, die Benutzeroberfläche für Nachrichten 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 Startseite des Add-ons 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 führt das Add-on die entsprechende kontextbezogene Triggerfunktion aus, die im Add-on Manifest 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 Nachrichten für diese Nachricht, die Gmail dem Nutzer dann anzeigt.

Nachrichten-Add-on erstellen

So fügen Sie einem Add-on Nachrichtenfunktionen hinzu:

1. Fügen Sie dem Manifest des Add-on-Skript projekts die entsprechenden Felder hinzu, einschließlich der für die Nachrichtenfunktionen erforderlichen Bereiche. Fügen Sie dem Manifest ein Feld für bedingte Trigger mit dem unconditional Wert {} hinzu.
2. Implementieren Sie eine kontextbezogene Triggerfunktion, die eine Benutzeroberfläche für Nachrichten erstellt, wenn der Nutzer das Add-on in einer Nachricht auswählt.
3. 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 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 die Triggerkriterien erfüllt* wird der Trigger ausgelöst. Ein ausgelöster Trigger führt eine kontextbezogene Triggerfunktion aus, die die Benutzeroberfläche des Add-ons erstellt und sie zur Anzeige an Gmail zurückgibt. An diesem Punkt kann der Nutzer mit der Benutzeroberfläche interagieren.

Kontextbezogene Trigger werden im Projekt manifest Ihres Add-ons definiert. Die Triggerdefinition gibt Gmail an, welche Triggerfunktion unter welchen Bedingungen ausgelöst werden soll. Mit dem folgenden Manifest-Snippet 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 Ihres Add-ons erstellt. Sie geben diese Funktion im Feld onTriggerFunction Ihres Manifests an. Sie implementieren diese Funktion so, dass sie ein Aktionsereignisobjekt als Argument akzeptiert und entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgibt.

Wenn ein kontextbezogener Trigger für eine bestimmte Gmail-Nachricht ausgelöst wird, ruft er diese Funktion auf und übergibt ihr ein Aktionsereignisobjekt. Häufig verwenden Triggerfunktionen die Nachrichten-ID, die von diesem Ereignisobjekt bereitgestellt wird, um den Nachrichtentext und andere Details mit dem Gmail-Dienst von Apps Script abzurufen. In den meisten Fällen müssen Sie Gmail-Bereiche mit dem vom Ereignisobjekt bereitgestellten Zugriffstoken und der GmailApp.setCurrentMessageAccessToken(accessToken) Funktion aktivieren, bevor Sie andere Gmail -Dienst-Funktionen verwenden. Mit den folgenden Funktionen kann Ihre Triggerfunktion beispielsweise 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 Benutzeroberfläche benötigt werden. Ein Add-on, das beispielsweise Umsatzzahlen zusammenfasst, kann Umsatzdaten aus dem Nachrichtentext erfassen und sie zur Anzeige auf einer Karte organisieren.

Die Triggerfunktion muss ein Array mit 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}