Azioni universali

Le azioni universali sono elementi di voci di menu che consentono a un utente di aprire una nuova pagina web, visualizzare nuove schede dell'interfaccia utente o eseguire una specifica funzione di Apps Script quando vengono selezionate. Dal punto di vista del funzionamento sono molto simili alle azioni delle schede, tranne per il fatto che le azioni universali vengono sempre posizionate in ogni scheda del componente aggiuntivo, indipendentemente dal contesto corrente del componente aggiuntivo.

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

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

Ogni volta che hai un'azione che non dipende dal contesto corrente, considera la possibilità di renderla un'azione universale.

Utilizzare le azioni universali

Le azioni universali sono configurate nel manifest del progetto del componente aggiuntivo. Una volta configurata, un'azione universale sarà sempre disponibile per gli utenti del tuo componente aggiuntivo. Se l'utente visualizza una scheda, l'insieme di azioni universali che hai definito viene sempre visualizzato nel menu della scheda, dopo eventuali azioni della scheda che hai definito per la scheda in questione. Le azioni universali vengono visualizzate nei menu delle schede nello stesso ordine in cui sono definite nel file manifest del componente aggiuntivo.

Configurazione delle azioni universali

Configura le azioni universali nel file manifest del componente aggiuntivo. Per ulteriori dettagli, consulta la sezione File manifest.

Per ogni azione, specifica il testo da visualizzare nel menu per quell'azione. Puoi quindi specificare un campo openLink che indichi che l'azione deve 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 eseguire quando viene selezionata l'azione universale.

Quando viene utilizzato runFunction, la funzione di callback specificata esegue in genere una delle seguenti operazioni:

• Crea schede dell'interfaccia utente da visualizzare immediatamente restituendo un oggetto UniversalActionResponse costruito.
• Apre un URL, ad esempio dopo aver svolto altre attività, restituendo un oggettoUniversalActionResponse compilato.
• Esegue 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, alla funzione di callback viene passato un oggetto evento contenente informazioni sulla scheda aperta e sul contesto del componente aggiuntivo.

Avviso: per mantenere i componenti aggiuntivi reattivi, il servizio Schede limita le funzioni di callback delle azioni universali a un massimo di 30 secondi di tempo di esecuzione. Se l'esecuzione richiede più tempo, l'interfaccia utente del componente aggiuntivo potrebbe non aggiornare correttamente la visualizzazione.

Esempio

Il seguente snippet di codice mostra un esempio di estratto del file manifest per un componente aggiuntivo Google Workspace che utilizza azioni universali e allo stesso tempo estende Gmail. Il codice imposta esplicitamente un ambito dei metadati in modo che il plug-in possa 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 eseguono le seguenti operazioni:

• Apri google.com apre https://www.google.com in una nuova scheda.
• Apri URL contatto esegue una funzione che determina l'URL da aprire e poi lo apre in una nuova scheda utilizzando un oggetto OpenLink. Il codice genera l'URL utilizzando l'indirizzo email del mittente.
• Apri impostazioni esegue la funzione createSettingsCards() definita nel progetto dello script del componente aggiuntivo. Questa funzione restituisce un oggetto UniversalActionResponse valido contenente un insieme di schede con l'impostazione del componente aggiuntivo e altre informazioni. Al termine della creazione di questo oggetto, l'interfaccia utente mostra l'elenco delle schede (consulta Restituire più schede).
• Esegui sincronizzazione in background esegue la funzione runBackgroundSync() definita nel progetto dello script del componente aggiuntivo. Questa funzione non crea schede, ma esegue altre attività in background che non modificano l'interfaccia utente. Poiché la funzione non restituisce un UniversalActionResponse, l'interfaccia utente non mostra una nuova scheda al termine della funzione. Al suo posto, la UI mostra un indicatore di caricamento mentre la funzione è in esecuzione.

Ecco un esempio di come creare le funzioni openContactURL(), 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.
}