Benutzeroberfläche für Nachrichten erweitern

Google Workspace Add-ons zur Erweiterung von Gmail bieten eine Benutzeroberfläche, wenn der Nutzer Nachrichten liest. Dadurch könnenGoogle Workspace Add-ons Aufgaben automatisieren, die auf Nachrichteninhalte reagieren, z. B. das Anzeigen, Abrufen oder Senden zusätzlicher Informationen im Zusammenhang mit der Nachricht.

Auf die UI für Add-on-Nachrichten zugreifen

Es gibt zwei Möglichkeiten, die Benutzeroberfläche 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 die Add-on-Startseite im Gmail-Posteingangsfenster angezeigt wird. Alternativ können Sie das Add-on starten, während Sie sich eine Nachricht ansehen.

In beiden Fällen führt das Add-on die entsprechende Funktion für den kontextabhängigen Trigger 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 Kontext-Trigger-Funktion erstellt die Nachrichten-UI für diese Nachricht, die Gmail dem Nutzer dann anzeigt.

Add-on für Nachrichten erstellen

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

  1. Fügen Sie dem Add-on-Skriptprojekt die Manifestdateien hinzu, einschließlich der Bereiche, die für die Nachrichtenfunktion erforderlich sind. Sie müssen dem Manifest ein bedingtes Triggerfeld mit dem unconditional-Wert {} hinzufügen.
  2. Implementieren Sie eine kontextabhängige Trigger-Funktion, mit der eine Nachrichten-UI erstellt wird, wenn der Nutzer das Add-on in einer Nachricht auswählt.
  3. Verknüpfte Funktionen implementieren, die für die Reaktion auf die UI-Interaktionen des Nutzers erforderlich sind

Kontextbezogene Trigger

Damit Nutzer beim Lesen von Nachrichten Unterstützung erhalten, könnenGoogle Workspace Add-ons einen kontextabhängigen Trigger in ihren Manifesten definieren. Wenn der Nutzer eine Gmail-Nachricht mit aktiviertem Add-on öffnet, die die Trigger-Kriterien* erfüllt, wird der Trigger ausgelöst. Ein ausgelöster Trigger führt eine kontextabhängige Trigger-Funktion aus, die die Add-on-Benutzeroberfläche erstellt und sie für Gmail wieder anzeigt. Dann kann der Nutzer damit interagieren.

Kontexttrigger werden im Manifest Ihres Add-ons definiert. Die Triggerdefinition teilt Gmail mit, welche Triggerfunktion unter welchen Bedingungen ausgelöst werden soll. Dieses Manifest-Snippet legt beispielsweise einen bedingungsfreien Trigger fest, der die Trigger-Funktion onGmailMessageOpen() beim Öffnen einer Nachricht aufruft:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Kontextbasierte Triggerfunktion

Jeder kontextabhängige Trigger muss eine entsprechende Triggerfunktion haben, mit der die Add-on-Benutzeroberfläche erstellt wird. Sie geben diese Funktion im Feld onTriggerFunction Ihres Manifests an. Sie implementieren diese Funktion, um ein 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, ruft er diese Funktion auf und übergibt ihr ein Aktionsereignisobjekt. Trigger verwenden häufig die von diesem Ereignisobjekt bereitgestellte Nachrichten-ID, um den Nachrichtentext und andere Details mit dem Gmail-Dienst von Apps Script abzurufen. Die Triggerfunktion könnte beispielsweise den Nachrichteninhalt mit diesen Funktionen 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 sie für die Schnittstelle benötigt. Mit einem Add-on, das die Verkaufszahlen zusammenfasst, können Sie 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, die den Betreff und den Absender der Nachricht enthält:

  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];
  }