Die Benutzeroberfläche für Mitteilungen erweitern

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. das Anzeigen, Abrufen oder Senden zusätzlicher Informationen im Zusammenhang mit der Nachricht.

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 Startseite des Add-ons im Gmail-Posteingangfenster aufrufen). 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 Kontext-Triggerfunktion aus, die im Manifest des Add-ons 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 kontextbezogene Triggerfunktion erstellt die Benutzeroberfläche für diese Nachricht, die dann in Gmail angezeigt wird.

Mitteilungs-Add-on erstellen

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

  1. Fügen Sie dem Add-on-Scriptprojekt die entsprechenden Felder zum Manifest hinzu, einschließlich der Bereiche, die für die Nachrichtenfunktion erforderlich sind. Fügen Sie dem Manifest ein Feld für bedingte Trigger mit dem Wert {} für unconditional hinzu.
  2. Implementieren Sie eine kontextabhängige Triggerfunktion, die eine Nachrichten-UI erstellt, wenn der Nutzer das Add-on in einer Nachricht auswählt.
  3. Implementieren Sie zugehörige Funktionen, die erforderlich sind, um auf die Interaktionen der Nutzer mit der Benutzeroberfläche zu reagieren.

Kontextabhängige Trigger

Damit Nutzer beim Lesen von Nachrichten Unterstützung erhalten, können Google Workspace-Add-ons in ihren Manifesten einen kontextbezogenen Trigger definieren. Wenn der Nutzer eine Gmail-Nachricht öffnet (bei geöffnetem Add-on), 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 in Gmail anzeigt. Ab diesem Zeitpunkt kann der Nutzer damit interagieren.

Kontextbezogene Trigger werden im Manifest des Add-ons definiert. In der Triggerdefinition wird Gmail mitgeteilt, welche Triggerfunktion unter welchen Bedingungen ausgelöst werden soll. In diesem Manifest-Snippet wird beispielsweise ein unbedingter Trigger festgelegt, der die Triggerfunktion onGmailMessageOpen() aufruft, wenn eine Nachricht geöffnet wird:

{
  ...
  "addOns": {

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

Kontextauslöserfunktion

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, um ein Argument vom Typ Ereignisobjekt vom Typ „Aktion“ 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 Ereignisobjekt für Aktionen übergeben. Triggerfunktionen verwenden häufig die Nachrichten-ID, die von diesem Ereignisobjekt bereitgestellt wird, um den Nachrichtentext und andere Details über den Gmail-Dienst von Apps Script abzurufen. 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 für die Benutzeroberfläche erforderlichen Informationen extrahieren. Ein Add-on, das Verkaufszahlen zusammenfasst, kann beispielsweise Verkaufszahlen aus dem Nachrichtentext erfassen und für die Anzeige auf einer Karte organisieren.

Die Triggerfunktion muss ein Array von erstellten Card-Objekten erstellen und zurückgeben. Mit dem folgenden Code wird beispielsweise ein Add-on mit einer einzelnen Karte erstellt, auf der nur Betreff und 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];
  }