Diese Seite wurde von der Cloud Translation API übersetzt.

Universelle Aktionen

Universelle Aktionen sind Menüelemente, mit denen Nutzer eine neue Webseite öffnen, neue UI-Karten anzeigen oder bei Auswahl eine bestimmte Apps Script-Funktion ausführen können. In ihrem Betrieb sind sie den Kartenaktionen sehr ähnlich, 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 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 sind einige Beispiele für Anwendungsfälle für universelle Aktionen:

Öffnen Sie eine Webseite mit den Einstellungen oder zeigen Sie eine Einstellungskarte an.
Zeigen Sie dem Nutzer Hilfeinformationen.
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 Sie eine Aktion haben, die nicht vom aktuellen Kontext abhängig ist, sollten Sie sie zu einer universellen Aktion machen.

Universelle Aktionen verwenden

Universelle Aktionen werden im Projektmanifest des Add-ons konfiguriert. Nachdem Sie eine universelle Aktion konfiguriert haben, ist sie für die Nutzer Ihres Add-ons immer verfügbar. Wenn der Nutzer eine Karte aufruft, werden die von Ihnen definierten universellen Aktionen immer im Anschluss an alle Kartenaktionen, die Sie für diese Karte definiert haben, 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

Sie konfigurieren universelle Aktionen im Manifest des Add-ons. 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, mit dem festgelegt wird, dass durch die Aktion eine Webseite direkt in einem neuen Tab geöffnet werden soll. Alternativ können Sie das Feld runFunction angeben, das eine Apps Script-Callback-Funktion angibt, die ausgeführt werden soll, wenn die universelle Aktion ausgewählt wird.

Bei Verwendung von runFunction führt die angegebene Callback-Funktion normalerweise einen der folgenden Schritte 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, die nicht zu einer neuen Karte wechseln oder eine URL öffnen. In diesem Fall gibt die Callback-Funktion nichts zurück.

Beim Aufruf wird an die Callback-Funktion ein Ereignisobjekt übergeben, das Informationen über die geöffnete Karte und den Add-on-Kontext enthält.

Beispiel

Das folgende Code-Snippet zeigt einen beispielhaften Manifestauszug für ein Google Workspace-Add-on, das bei der Erweiterung von Gmail universelle Aktionen verwendet. Mit dem Code wird explizit ein Metadatenbereich festgelegt, sodass das Add-on bestimmen 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 im vorherigen Beispiel definierten universellen Aktionen führen zu Folgendem:

Open google.com öffnet https://www.google.com in einem neuen Tab.
Open contact URL (Kontakt-URL öffnen) führt eine Funktion aus, die bestimmt, welche URL geöffnet werden soll, und diese dann mithilfe eines OpenLink-Objekts in einem neuen Tab öffnet. Der Code erstellt die URL anhand der E-Mail-Adresse des Absenders.
Open settings (Einstellungen öffnen) führt die Funktion createSettingsCards() aus, die im Add-on-Skriptprojekt definiert ist. 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 auf der UI die Liste der Karten angezeigt (siehe Mehrere Karten zurückgeben).
Mit Hintergrundsynchronisierung ausführen wird die Funktion runBackgroundSync() ausgeführt, die im Add-on-Skriptprojekt definiert ist. Diese Funktion erstellt keine Karten, sondern führt einige andere Hintergrundaufgaben aus, die die UI nicht ä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 während der Ausführung der Funktion ein Ladesymbol angezeigt.

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