Universelle Aktionen

Universelle Aktionen sind Menüelemente, mit denen Nutzer eine neue Webseite öffnen, neue UI-Karten anzeigen oder eine bestimmte Apps Script-Funktion ausführen können. Sie funktionieren ähnlich wie Kartenaktionen, mit dem Unterschied, dass universelle Aktionen unabhängig vom aktuellen Add-on-Kontext immer auf jeder Karte in Ihrem Add-on platziert werden.

Mithilfe universeller Aktionen können Sie dafür sorgen, dass Nutzer immer Zugriff auf bestimmte Funktionen haben, unabhängig davon, mit welchem Teil Ihres Add-ons sie interagieren. Hier einige Anwendungsfälle für universelle Aktionen:

• Öffnen Sie eine Webseite mit den Einstellungen oder zeigen Sie eine Einstellungskarte an.
• Dem Nutzer Hilfeinformationen anzeigen
• Starten Sie einen neuen Workflow, z. B. „Neuen Kunden hinzufügen“.
• Eine Karte anzeigen, über die Nutzer Feedback zum Add-on senden können.

Wenn eine Aktion nicht vom aktuellen Kontext abhängt, sollten Sie sie als universelle Aktion festlegen.

Universelle Aktionen verwenden

Universale Aktionen werden im Manifest des Add-ons konfiguriert. Nachdem Sie eine universelle Aktion konfiguriert haben, ist sie für Nutzer Ihres Add-ons immer verfügbar. Wenn sich der Nutzer eine Karte ansieht, werden die von Ihnen definierten universellen Aktionen immer im Kartenmenü angezeigt, nach allen Kartenaktionen, die Sie für diese Karte definiert haben. Universelle Aktionen werden in den Kartenmenüs in der Reihenfolge angezeigt, in der sie im Manifest des Add-ons definiert sind.

Universelle Aktionen konfigurieren

Sie konfigurieren universelle Aktionen im Manifest Ihres Add-ons. Weitere Informationen finden Sie unter Manifeste.

Geben Sie für jede Aktion den Text an, der im Menü für diese Aktion angezeigt werden soll. Sie können dann ein openLink-Feld angeben, das angibt, dass die Aktion eine Webseite direkt in einem neuen Tab öffnen soll. Alternativ können Sie ein runFunction-Feld angeben, das eine Apps Script-Callback-Funktion angibt, die ausgeführt werden soll, wenn die universelle Aktion ausgewählt wird.

Wenn runFunction verwendet wird, führt die angegebene Callback-Funktion in der Regel eine der folgenden Aktionen aus:

• Erstellt UI-Karten, die sofort angezeigt werden, indem ein erstelltes UniversalActionResponse-Objekt zurückgegeben wird.
• Öffnet eine URL, möglicherweise nach anderen Aufgaben, indem ein erstelltes UniversalActionResponse-Objekt zurückgegeben wird.
• Führt Hintergrundaufgaben aus, bei denen nicht zu einer neuen Karte gewechselt oder eine URL geöffnet wird. In diesem Fall gibt die Rückruffunktion nichts zurück.

Bei der Aufrufung wird der Callback-Funktion ein Ereignisobjekt übergeben, das Informationen zur geöffneten Karte und zum Add-on-Kontext enthält.

Warnung: Damit die Add-ons reaktionsschnell bleiben, begrenzt der Kartendienst die Ausführungszeit von Rückruffunktionen für universelle Aktionen auf maximal 30 Sekunden. Wenn die Ausführung länger dauert, wird die Benutzeroberfläche des Add-ons möglicherweise nicht richtig aktualisiert.

Beispiel

Das folgende Code-Snippet zeigt einen Beispielauszug aus dem Manifest für ein Google Workspace-Add-on, das universelle Aktionen verwendet und Gmail erweitert. Im Code wird explizit ein Metadatenbereich festgelegt, damit das Add-on ermitteln kann, wer die geöffnete Nachricht gesendet hat.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

Die drei universellen Aktionen, die im vorherigen Beispiel definiert wurden, führen Folgendes aus:

• Wenn Sie google.com öffnen auswählen, wird https://www.google.com in einem neuen Tab geöffnet.
• Mit Kontakt-URL öffnen wird eine Funktion ausgeführt, die bestimmt, welche URL geöffnet werden soll, und öffnet sie dann mit einem OpenLink-Objekt in einem neuen Tab. Der Code erstellt die URL anhand der E-Mail-Adresse des Absenders.
• Wenn Sie Einstellungen öffnen auswählen, wird die im Add-on-Scriptprojekt definierte Funktion createSettingsCards() ausgeführt. Diese Funktion gibt ein gültiges UniversalActionResponse-Objekt zurück, das eine Reihe von Karten mit Add-on-Einstellungen und anderen Informationen enthält. Nachdem die Funktion dieses Objekt erstellt hat, wird in der Benutzeroberfläche die Liste der Karten angezeigt (siehe Mehrere Karten zurückgeben).
• Mit Hintergrundsynchronisierung ausführen wird die im Add-on-Scriptprojekt definierte Funktion runBackgroundSync() ausgeführt. Mit dieser Funktion werden keine Karten erstellt, sondern andere Hintergrundaufgaben ausgeführt, die die Benutzeroberfläche nicht ändern. Da die Funktion keine UniversalActionResponse zurückgibt, wird in der Benutzeroberfläche nach Abschluss der Funktion keine neue Karte angezeigt. Stattdessen wird in der Benutzeroberfläche ein rotierendes Ladesymbol angezeigt, während die Funktion ausgeführt wird.

Hier ist ein Beispiel dafür, wie Sie die Funktionen openContactURL(), createSettingsResponse() und runBackgroundSync() erstellen können:

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}