Acciones universales

Las acciones universales son elementos de elementos de menú que permiten al usuario abrir una página web nueva, mostrar tarjetas de IU nuevas o ejecutar una función específica de Apps Script cuando se seleccionan. En su funcionamiento, son muy similares a las acciones de tarjetas, excepto que las acciones universales siempre se colocan en cada tarjeta de tu complemento, independientemente del contexto actual del complemento.

Cuando usas acciones universales, puedes asegurarte de que el usuario siempre tenga acceso a ciertos atributos, independientemente de con qué parte del complemento interactúe. Estos son algunos ejemplos de casos de uso para acciones universales:

  • Abre una página web de configuración (o muestra una tarjeta de configuración).
  • Muestra información de ayuda al usuario.
  • Inicia un flujo de trabajo nuevo, como "Agregar cliente nuevo".
  • Muestra una tarjeta que le permite al usuario enviar comentarios sobre el complemento.

Siempre que tengas una acción que no dependa del contexto actual, debes considerar convertirla en una acción universal.

Cómo usar acciones universales

Las acciones universales se configuran en el manifiesto del proyecto de tu complemento. Una vez que configures una acción universal, esta siempre estará disponible para los usuarios de tu complemento. Si el usuario está viendo una tarjeta, el conjunto de acciones universales que definiste siempre aparece en el menú de la tarjeta, después de las acciones de la tarjeta que definiste para esa tarjeta. Las acciones universales aparecen en los menús de tarjetas en el mismo orden en que se definen en el manifiesto del complemento.

Cómo configurar acciones universales

Las acciones universales se configuran en el manifiesto del complemento. Consulta Manifiestos para obtener más detalles.

Para cada acción, especificas el texto que debe aparecer en el menú de esa acción. Luego, puedes especificar un campo openLink que indique que la acción debe abrir directamente una página web en una pestaña nueva. Como alternativa, puedes especificar un campo runFunction que especifique una función de devolución de llamada de Apps Script para que se ejecute cuando se seleccione la acción universal.

Cuando se usa runFunction, la función de devolución de llamada especificada suele hacer una de las siguientes acciones:

  • Compila tarjetas de IU para mostrarlas de inmediato mostrando un objeto UniversalActionResponse compilado.
  • Devuelve un objeto UniversalActionResponse compilado para abrir una URL, quizás después de realizar otras tareas.
  • Realiza tareas en segundo plano que no cambian a una tarjeta nueva ni abren una URL. En este caso, la función de devolución de llamada no muestra nada.

Cuando se llama a la función de devolución de llamada, se le pasa un objeto de evento que contiene información sobre la tarjeta abierta y el contexto del complemento.

Ejemplo

En el siguiente fragmento de código, se muestra un extracto de manifiesto de ejemplo para un complemento de Google Workspace que usa acciones universales mientras extiende Gmail. El código establece explícitamente un alcance de metadatos para que el complemento pueda determinar quién envió el mensaje abierto.

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

Las tres acciones universales definidas en el ejemplo anterior hacen lo siguiente:

  • Abrir google.com abre https://www.google.com en una pestaña nueva.
  • Abrir URL de contacto ejecuta una función que determina qué URL abrir y, luego, la abre en una pestaña nueva con un objeto OpenLink. El código compila la URL con la dirección de correo electrónico del remitente.
  • Abrir configuración ejecuta la función createSettingsCards() definida en el proyecto de secuencia de comandos del complemento. Esta función muestra un objeto UniversalActionResponse válido que contiene un conjunto de tarjetas con la configuración del complemento y otra información. Después de que la función termine de compilar este objeto, la IU mostrará la lista de tarjetas (consulta Cómo mostrar varias tarjetas).
  • Ejecutar sincronización en segundo plano ejecuta la función runBackgroundSync() definida en el proyecto de secuencia de comandos del complemento. Esta función no compila tarjetas, sino que realiza otras tareas en segundo plano que no cambian la IU. Como la función no muestra un UniversalActionResponse, la IU no muestra una tarjeta nueva cuando finaliza la función. En su lugar, la IU muestra un ícono giratorio del indicador de carga mientras se ejecuta la función.

A continuación, se muestra un ejemplo de cómo podrías construir las funciones openContactURL(), createSettingsResponse() y 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.
}