Universelle Aktionen

Universelle Aktionen sind Menüelemente, mit denen Nutzer ein neues neue UI-Karten anzeigen oder eine bestimmte Apps Script-Funktion ausführen, ausgewählt. In der Praxis sind sie ähnlich wie Kartenaktionen, nur dass universelle Aktionen immer auf jeder Karte in Ihrem Add-on platziert werden, unabhängig vom aktuellen Kontext des Add-ons.

Mit universellen Aktionen können Sie dafür sorgen, dass der Nutzer immer Zugriff auf bestimmte Funktionen nutzen, unabhängig davon, mit welchem Teil des Add-ons sie interagieren, mit. 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

Immer wenn Sie eine Aktion haben, die nicht vom aktuellen Kontext abhängt, sollten Sie sie zu einer universellen Aktion machen.

Universelle Aktionen verwenden

Im Projekt des Add-ons wurden universelle Aktionen konfiguriert Manifest herunter. Nachdem Sie eine universelle Aktion haben, steht sie den Nutzern Ihres Add-ons immer zur Verfügung. Wenn der Nutzer gerade eine Karte ansieht, werden die von Ihnen definierten universellen Aktionen immer im Kartenmenü klicken, nachdem Kartenaktionen die Sie für diese Karte definiert haben. Universelle Aktionen erscheinen in den Kartenmenüs in der in derselben Reihenfolge im Manifest des Add-ons definiert.

Universelle Aktionen konfigurieren

Universelle Aktionen werden im Manifest Ihres Add-ons konfiguriert. Siehe Manifeste .

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

Wenn runFunction verwendet wird, führt die angegebene Callback-Funktion normalerweise eine zu verwenden:

• Erstellt UI-Karten so, dass sie sofort angezeigt werden, indem ein UniversalActionResponse -Objekt enthält.
• Öffnet eine URL, z. B. nach der Erledigung anderer Aufgaben, indem ein erstelltes UniversalActionResponse-Objekt.
• 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 mit Informationen zur geöffneten Karte und zum Kontext des Add-ons.

Achtung :Damit die Add-ons reaktionsschnell bleiben, muss der Kartendienst beschränkt die Callback-Funktionen für universelle Aktionen auf maximal 30 Sekunden Ausführungszeit. Wenn die Ausführung länger dauert, wird die Add-on-UI möglicherweise aktualisiert wird.

Beispiel

Das folgende Code-Snippet zeigt ein Beispiel-Manifest-Auszug für ein Google Workspace-Add-on, das universelle Aktionen verwendet während Sie Gmail erweitern. Der Code legt explizit einen Metadatenbereich fest, sodass der kann das Add-on ermitteln, 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 einen neuen Tab öffnen.
• Kontakt-URL öffnen führt eine Funktion aus, die bestimmt, welche URL geöffnet werden soll und öffnet sie dann in einem neuen Tab mit einem OpenLink-Objekt. Die -Code erstellt die URL anhand der E-Mail-Adresse des Absenders.
• Mit Einstellungen öffnen wird die in folgendem Dokument definierte Funktion createSettingsCards() ausgeführt: für das Add-on-Skriptprojekt. Diese Funktion gibt eine gültige UniversalActionResponse Objekt, das eine Reihe von Karten mit Add-on-Einstellungen und anderen Informationen enthält. Nachdem die Funktion dieses Objekt erstellt hat, zeigt die Benutzeroberfläche die Liste von Karten (siehe Mehrere Karten zurückgeben.
• Hintergrundsynchronisierung ausführen führt die Funktion runBackgroundSync() aus, die im Add-on-Skriptprojekts. Diese Funktion erstellt keine Karten. stattdessen Er führt einige andere Hintergrundaufgaben aus, die die Benutzeroberfläche nicht verändern. Da die gibt die Funktion kein UniversalActionResponse, In der Benutzeroberfläche wird keine neue Karte angezeigt, wenn die Funktion beendet ist. Stattdessen Auf der Benutzeroberfläche wird ein rotierendes Ladesymbol angezeigt, während die Funktion ausgeführt wird.

Hier ist ein Beispiel dafür, wie du das openContactURL()-Objekt konstruieren könntest, createSettingsResponse()- und runBackgroundSync()-Funktionen:

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