Acciones universales

Las acciones universales son elementos de elementos de menú que permiten al usuario abrir una mostrar nuevas tarjetas de IU o ejecutar una función específica de Apps Script cuando seleccionado. En operación, son muy similares a acciones de tarjeta, salvo que las acciones universales siempre se colocan en cada tarjeta independientemente del contexto actual del complemento.

Con las acciones universales, puedes asegurarte de que el usuario siempre tenga acceso a ciertas funcionalidades, independientemente de la parte del complemento con la que interactúen tus amigos. Estos son algunos ejemplos de casos de uso para las 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".
  • Mostrar una tarjeta que permita al usuario enviar comentarios sobre el complemento

Cuando tienes una acción que no depende del contexto actual, deberías considerar convertirla en una acción universal.

Cómo usar acciones universales

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

Cómo configurar acciones universales

Puedes configurar acciones universales en el manifiesto de tu complemento. ver Manifiestos para obtener más información.

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 debería abrir directamente una página web en una pestaña nueva. Como alternativa, puedes especificar un campo runFunction que especifica una función de devolución de llamada de Apps Script para ejecutar cuando se selecciona la acción universal.

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

  • Compila tarjetas de IU para mostrar de inmediato devolviendo una compilación UniversalActionResponse .
  • Abre una URL, quizás después de realizar otras tareas, cuando muestra un archivo UniversalActionResponse.
  • Realiza tareas en segundo plano que no cambian a una nueva tarjeta ni abren una URL. En este caso, la función de devolución de llamada no devuelve nada.

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

Ejemplo

El siguiente fragmento de código muestra un ejemplo de extracto de manifiesto para un un complemento de Google Workspace que usa acciones universales al tiempo que extiendes Gmail. El código establece explícitamente un alcance de metadatos para que el puede 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 nueva pestaña.
  • Abrir URL de contacto ejecuta una función que determina qué URL abrir y, luego, lo abre en una pestaña nueva con un objeto OpenLink. El código crea 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 valor válido UniversalActionResponse que contiene un conjunto de tarjetas con la configuración de un complemento y otra información. Cuando la función termine de compilar el objeto, la IU mostrará la lista de tarjetas (consulta Devolver varias tarjetas).
  • Ejecutar la sincronización en segundo plano ejecuta la función runBackgroundSync() definida en el proyecto de secuencia de comandos del complemento. Esta función no crea tarjetas. en su lugar, realiza algunas otras tareas en segundo plano que no cambian la IU. Ya que el la función no devuelve un UniversalActionResponse: la IU no muestra una nueva tarjeta cuando finaliza la función. En cambio, el La IU muestra un ícono giratorio de indicador de carga mientras se ejecuta la función.

Este es un ejemplo de cómo podrías construir el openContactURL(): Funciones 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.
}