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.

Auf die Benutzeroberfläche für Nachrichten von Google Workspace-Add-ons 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 Funktion für kontextbezogene Trigger 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:

1. Fügen Sie dem Add-on-Skriptprojekt Manifest 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 Nachricht-Benutzeroberfläche 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 (mit geöffnetem Add‑on) öffnet, 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 Gerät 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 ihr wird 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. In den meisten Fällen müssen Sie Gmail-Bereiche mit dem vom Ereignisobjekt bereitgestellten Zugriffstoken und der Funktion GmailApp.setCurrentMessageAccessToken(accessToken) aktivieren, bevor Sie andere Gmail-Dienstfunktionen verwenden. 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}