Azioni universali

Le azioni universali sono elementi di voci di menu che consentono a un utente di aprire una nuova pagina web, visualizza nuove schede dell'interfaccia utente o esegui una funzione specifica di Apps Script selezionato. In funzione sono molto simili azioni della scheda, tranne per il fatto che le azioni universali sono sempre inserite in ogni scheda del componente aggiuntivo, a prescindere dal contesto attuale del componente aggiuntivo.

Utilizzando le azioni universali, puoi assicurarti che l'utente abbia sempre accesso a alcune funzionalità, indipendentemente dalla parte del componente aggiuntivo con cui interagiscono con. Ecco alcuni casi d'uso di esempio per le azioni universali:

• Apri una pagina web delle impostazioni (o visualizza una scheda delle impostazioni).
• Mostra le informazioni della guida all'utente.
• Avvia un nuovo flusso di lavoro, ad esempio "Aggiungi nuovo cliente".
• Mostrare una scheda che consenta all'utente di inviare feedback sul componente aggiuntivo.

Ogni volta che esegui un'azione che non dipende dal contesto corrente, dovresti considerare l'idea di renderlo un'azione universale.

Utilizzo delle azioni universali

Le azioni universali sono configurate nel progetto del componente aggiuntivo manifest. Una volta configurata una universale, è sempre disponibile per gli utenti del componente aggiuntivo. Se l'utente visualizza una scheda, l'insieme di azioni universali che hai definito compare sempre nel menu della scheda, dopo azioni della scheda che hai definito per la scheda in questione. Le azioni universali vengono visualizzate nei menu della scheda all'interno della nello stesso ordine in cui vengono definiti nel file manifest del componente aggiuntivo.

Configurazione delle azioni universali

Puoi configurare azioni universali nel file manifest del componente aggiuntivo. vedi Manifest per ulteriori dettagli.

Per ogni azione devi specificare il testo da visualizzare nel relativo menu. un'azione. Puoi quindi specificare un campo openLink per indicare che l'azione dovrebbe aprire direttamente una pagina web in una nuova scheda. In alternativa, puoi specificare un campo runFunction che specifica una funzione di callback di Apps Script da quando è selezionata l'azione universale.

Quando viene utilizzato runFunction, la funzione di callback specificata di solito esegue una dei seguenti:

• Crea schede UI da visualizzare immediatamente restituendo un codice UniversalActionResponse .
• Apre un URL, magari dopo aver eseguito altre attività, restituendo un URL UniversalActionResponse oggetto.
• Svolge attività in background che non passano a una nuova scheda o aprono un URL. In questo caso, la funzione di callback non restituisce nulla.

Quando viene chiamata, la funzione di callback viene passata oggetto evento contenente informazioni sulla scheda aperta e sul contesto del componente aggiuntivo.

Esempio

Il seguente snippet di codice mostra un estratto di manifest di esempio per una Componente aggiuntivo di Google Workspace che utilizza azioni universali ed estendendo Gmail. Il codice imposta esplicitamente un ambito dei metadati in modo che può determinare chi ha inviato il messaggio aperto.

  "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"
        }
      ]
    },
    ...
  },
  ...

Le tre azioni universali definite nell'esempio precedente:

• Apri google.com apre https://www.google.com in una nuova scheda.
• Apri URL contatto esegue una funzione che determina quale URL aprire e la apre in una nuova scheda utilizzando OpenLink. La crea l'URL utilizzando l'indirizzo email del mittente.
• Apri impostazioni esegue la funzione createSettingsCards() definita in il progetto di script del componente aggiuntivo. Questa funzione restituisce un valore UniversalActionResponse contenente un insieme di schede con impostazioni aggiuntive e altre informazioni. Dopo che la funzione termina la creazione dell'oggetto, la UI mostra l'elenco di schede (vedi Restituzione di più carte).
• Esegui sincronizzazione in background esegue la funzione runBackgroundSync() definita nella progetto di script del componente aggiuntivo. Questa funzione non crea schede; invece esegue altre attività in background che non modificano l'interfaccia utente. Poiché il non restituisce un UniversalActionResponse, l'interfaccia utente non mostra una nuova scheda al termine della funzione. Invece il UI che mostra una rotellina dell'indicatore di caricamento mentre la funzione è in esecuzione.

Ecco un esempio di come potresti costruire openContactURL(), Funzioni createSettingsResponse() e runBackgroundSync():

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