Universelle Aktionen

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

Mit universellen Aktionen können Sie dafür sorgen, dass der Nutzer immer Zugriff auf bestimmte Funktionen hat, unabhängig davon, mit welchem Teil Ihres Add-ons er interagiert. Hier einige Anwendungsbeispiele für universelle Aktionen:

• Webseite mit Einstellungen öffnen oder Karte mit Einstellungen anzeigen
• Dem Nutzer Hilfeinformationen anzeigen
• Starten Sie einen neuen Workflow, z. B. „Neuen Kunden hinzufügen“.
• Eine Karte anzeigen, auf der Nutzer Feedback zum Add-on geben können

Wenn Sie eine Aktion haben, die nicht vom aktuellen Kontext abhängt, sollten Sie sie in eine universelle Aktion umwandeln.

Universelle Aktionen verwenden

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

Universelle Aktionen konfigurieren

Universelle Aktionen werden im Manifest Ihres Add-ons konfiguriert. Weitere Informationen finden Sie unter Manifeste.

Für jede Aktion geben Sie den Text an, der im Menü für diese Aktion angezeigt werden soll. Sie können dann ein openLink-Feld angeben, das angibt, dass mit der Aktion eine Webseite direkt in einem neuen Tab geöffnet werden 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 ist.

Bei Verwendung von runFunction führt die angegebene Callback-Funktion in der Regel einen der folgenden Schritte aus:

• Erstellt UI-Karten, die sofort angezeigt werden, indem ein erstelltes UniversalActionResponse-Objekt zurückgegeben wird.
• Öffnet eine URL durch Zurückgeben eines erstellten UniversalActionResponse-Objekts, z. B. nach der Erledigung anderer Aufgaben.
• Führt Hintergrundaufgaben aus, bei denen nicht zu einer neuen Karte gewechselt oder eine URL geöffnet wird In diesem Fall gibt die Callback-Funktion nichts zurück.

Beim Aufruf 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 responsiv bleiben, beschränkt der Kartendienst die Callback-Funktionen für universelle Aktionen auf eine Ausführungszeit von maximal 30 Sekunden. Wenn die Ausführung länger dauert, wird die Anzeige der Add-on-UI möglicherweise nicht korrekt aktualisiert.

Beispiel

Das folgende Code-Snippet zeigt ein Beispiel-Manifest für ein Google Workspace-Add-on, das beim Erweitern von Gmail universelle Aktionen verwendet. Der Code legt explizit einen Metadatenbereich fest, damit das Add-on feststellen 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"
        }
      ]
    },
    ...
  },
  ...

Mit den drei im vorherigen Beispiel definierten universellen Aktionen wird Folgendes ausgeführt:

• google.com öffnen öffnet https://www.google.com in einem neuen Tab.
• Kontakt-URL öffnen führt eine Funktion aus, die bestimmt, welche URL geöffnet werden soll, und sie dann mithilfe eines OpenLink-Objekts in einem neuen Tab öffnet. Mit dem Code wird die URL anhand der E-Mail-Adresse des Absenders erstellt.
• Mit Einstellungen öffnen wird die im Add-on-Skriptprojekt definierte Funktion createSettingsCards() ausgeführt. Diese Funktion gibt ein gültiges UniversalActionResponse-Objekt zurück, das eine Reihe von Karten mit Add-on-Einstellung und anderen Informationen enthält. Nachdem die Funktion das Objekt erstellt hat, wird in der UI die Liste der Karten angezeigt (siehe Mehrere Karten zurückgeben).
• Mit Hintergrundsynchronisierung ausführen wird die im Add-on-Skriptprojekt definierte runBackgroundSync()-Funktion ausgeführt. Diese Funktion erstellt keine Karten. Stattdessen führt sie einige andere Aufgaben im Hintergrund aus, die die Benutzeroberfläche nicht verändern. Da die Funktion kein UniversalActionResponse zurückgibt, wird in der UI keine neue Karte angezeigt, wenn die Funktion abgeschlossen ist. Stattdessen wird auf der Benutzeroberfläche ein rotierendes Ladesymbol angezeigt, während die Funktion ausgeführt wird.

Das folgende Beispiel zeigt, 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.
}