Actions universelles

Les actions universelles sont des éléments d'éléments de menu qui permettent à un utilisateur d'ouvrir une nouvelle d'une page Web, d'afficher de nouvelles cartes d'interface utilisateur ou d'exécuter une fonction Apps Script spécifique sélectionnée. En fonctionnement, ils sont très similaires actions de la fiche, sauf que les actions universelles sont toujours placées sur chaque fiche de votre module complémentaire, quel que soit le contexte actuel du module complémentaire.

Grâce aux actions universelles, vous pouvez vous assurer que l'utilisateur a toujours accès à certaines fonctionnalités, quelle que soit la partie du module complémentaire . Voici quelques exemples d'utilisation d'actions universelles:

• Ouvrez une page Web de paramètres (ou affichez une fiche de paramètres).
• Afficher des informations d'aide pour l'utilisateur.
• Démarrez un nouveau workflow, par exemple "Ajouter un nouveau client".
• Afficher une fiche permettant aux utilisateurs d'envoyer des commentaires sur le module complémentaire.

Chaque fois que vous avez une action qui ne dépend pas du contexte actuel, vous devriez envisager d'en faire une action universelle.

Utiliser des actions universelles

Les actions universelles sont configurées dans le projet de votre module complémentaire manifest. Une fois que vous avez configuré une action universelle, elle est toujours à la disposition des utilisateurs de votre module complémentaire. Si l'utilisateur consulte une fiche, l'ensemble d'actions universelles que vous avez définies s'affiche toujours dans le menu de la fiche, après actions de la fiche que vous avez définies pour cette fiche. Les actions universelles s'affichent dans les menus des fiches dans le même ordre que celui défini dans le fichier manifeste du module complémentaire.

Configurer des actions universelles

Vous configurez des actions universelles dans le fichier manifeste du module complémentaire. voir Fichiers manifestes pour en savoir plus.

Pour chaque action, vous spécifiez le texte qui doit apparaître dans le menu pour cette action action. Vous pouvez ensuite spécifier un champ openLink indiquant que l'action doit ouvrir directement une page Web dans un nouvel onglet. Vous pouvez également spécifier Un champ runFunction qui spécifie une fonction de rappel Apps Script pour exécuter lorsque l'action universelle est sélectionnée.

Lorsque runFunction est utilisé, la fonction de rappel spécifiée effectue généralement une action des éléments suivants:

• Crée des cartes d'interface utilisateur à afficher immédiatement en renvoyant un UniversalActionResponse .
• Ouvre une URL, peut-être après avoir effectué d'autres tâches, en renvoyant une réponse générée UniversalActionResponse.
• effectue des tâches en arrière-plan qui ne basculent pas vers une nouvelle fiche et n'ouvrent pas d'URL. Dans ce cas, la fonction de rappel ne renvoie rien.

Lorsqu'elle est appelée, la fonction de rappel reçoit une Objet événement contenant des informations sur la fiche ouverte et le contexte du module complémentaire.

Avertissement :Pour que les modules complémentaires restent responsifs, le service de carte limite les fonctions de rappel d'action universelle à 30 secondes maximum le temps d'exécution. Si l'exécution prend plus de temps, l'UI de votre module complémentaire risque de ne pas correctement son affichage.

Exemple

L'extrait de code suivant présente un exemple d'extrait de fichier manifeste pour Module complémentaire Google Workspace utilisant des actions universelles tout en étendant Gmail. Le code définit explicitement un champ d'application des métadonnées, de sorte que peut déterminer qui a envoyé le message ouvert.

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

Les trois actions universelles définies dans l'exemple précédent effectuent les opérations suivantes:

• Ouvrir google.com ouvre https://www.google.com dans dans un nouvel onglet.
• Ouvrir l'URL de contact exécute une fonction qui détermine l'URL à ouvrir puis l'ouvre dans un nouvel onglet objet OpenLink. La crée l'URL en utilisant l'adresse e-mail de l'expéditeur.
• Open settings (Ouvrir les paramètres) exécute la fonction createSettingsCards() définie dans le projet du script du module complémentaire. Cette fonction renvoie une valeur UniversalActionResponse contenant un ensemble de fiches avec le paramètre du module complémentaire et d'autres informations. Une fois que la fonction a terminé de créer cet objet, l'interface utilisateur affiche la liste de cartes (voir Retourner plusieurs cartes)
• Exécuter la synchronisation en arrière-plan exécute la fonction runBackgroundSync() définie dans du script du module complémentaire. Cette fonction ne crée pas de fiches. mais plutôt effectue d'autres tâches en arrière-plan qui ne modifient pas l'UI. Depuis le ne renvoie pas de UniversalActionResponse l'UI n'affiche pas de nouvelle fiche une fois la fonction terminée. Le L'UI affiche une icône de chargement lorsque la fonction est en cours d'exécution.

Voici un exemple de construction de openContactURL(), Fonctions createSettingsResponse() et 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.
}