Universelle Aktionen

Universelle Aktionen sind Elemente von Menüs, mit denen ein Nutzer eine neue Webseite öffnen, neue UI-Karten anzeigen oder eine bestimmte Apps Script-Funktion ausführen kann. Sie sind ganz ähnlich wie Kartenaktionen, mit der Ausnahme, dass universelle Aktionen immer auf jeder Karte in Ihrem Add-on platziert werden, unabhängig vom aktuellen Add-on-Kontext.

Mit universellen Aktionen sorgen Sie dafür, dass der Nutzer immer Zugriff auf bestimmte Funktionen hat, unabhängig davon, mit welchem Teil des Add-ons er interagiert. Hier sind einige Beispiele für Anwendungsfälle für universelle Aktionen:

  • Öffnen Sie eine Webseite mit Einstellungen oder zeigen Sie eine Karte mit Einstellungen an.
  • Zeigen Sie dem Nutzer Hilfeinformationen an.
  • Einen neuen Workflow starten, 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 überlegen, sie zu einer universellen Aktion zu machen.

Universelle Aktionen verwenden

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

Universelle Aktionen konfigurieren

Sie konfigurieren universelle Aktionen in Ihrem Add-on-Manifest. 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. Anschließend kannst du das Feld openLink angeben, um anzugeben, dass 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.

Wenn runFunction verwendet wird, 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, z. B. nach der Ausführung anderer Aufgaben, indem ein erstelltes UniversalActionResponse-Objekt zurückgegeben wird.
  • Führt Hintergrundaufgaben durch, 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.

Beispiel

Das folgende Code-Snippet zeigt ein Beispiel für einen Manifestauszug für ein Add-onGoogle Workspace , das beim Erweitern von Gmail universelle Aktionen verwendet. Der Code legt explizit einen Metadatenbereich fest, damit das Add-on feststellen kann, wer die offene 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 oben beschriebenen universellen Aktionen führen zu folgenden Aktionen:

  • Öffne google.com und öffnet https://www.google.com in einem neuen Tab.
  • Open contact URL (Kontakt-URL öffnen) führt eine Funktion aus, die ermittelt, welche URL geöffnet werden soll, und sie dann in einem neuen Tab mit einem OpenLink-Objekt öffnet. Der Code erstellt die URL anhand der E-Mail-Adresse des Absenders.
  • In den Einstellungen öffnen wird die im Add-on-Skript-Projekt 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 weitere Informationen enthält. Nachdem die Funktion dieses Objekts erstellt hat, wird in der UI die Liste der Karten angezeigt (siehe Mehrere Karten zurückgeben).
  • Mit der Hintergrundsynchronisierung wird die im Add-on-Skript-Projekt definierte Funktion runBackgroundSync() ausgeführt. Mit dieser Funktion werden keine Karten erstellt. Stattdessen werden einige andere Hintergrundaufgaben ausgeführt, die die Benutzeroberfläche nicht ändern. Da von der Funktion kein UniversalActionResponse zurückgegeben wird, zeigt die UI nach Abschluss der Funktion keine neue Karte an. Stattdessen zeigt die Benutzeroberfläche ein Ladesymbol an, während die Funktion ausgeführt wird.

Hier siehst du ein Beispiel dafür, wie du die Funktionen openContactURL(), createSettingsResponse() und runBackgroundSync() konstruieren kannst:

/**
 * 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.
}