Benutzeroberfläche für Nachrichten erweitern

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:

  1. 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.
  2. Kontextbezogene Triggerfunktion implementieren, die eine Nachrichten-UI erstellt, wenn der Nutzer das Add-on in einer Nachricht auswählt.
  3. 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];
  }