Estendere l'interfaccia utente dei messaggi

I componenti aggiuntivi di Google Workspace che estendono Gmail possono fornire un'interfaccia utente quando l'utente legge i messaggi. Ciò consente ai componenti aggiuntivi di automatizzare le attività che rispondono ai contenuti dei messaggi, ad esempio la visualizzazione, il recupero o l'invio di informazioni aggiuntive relative al messaggio.

Accedere all'interfaccia utente dei messaggi del componente aggiuntivo di Google Workspace

Esistono due modi per visualizzare l'interfaccia utente dei messaggi di un componente aggiuntivo. Il primo modo è aprire un messaggio mentre il componente aggiuntivo è già aperto (ad esempio, quando visualizzi la home page del componente aggiuntivo nella finestra della posta in arrivo di Gmail). Il secondo modo è avviare il componente aggiuntivo mentre visualizzi un messaggio.

In entrambi i casi, il componente aggiuntivo esegue la funzione di attivazione contestuale definita nel manifest del componente aggiuntivo. Il trigger viene eseguito anche se l'utente passa a un altro messaggio mentre il componente aggiuntivo è ancora aperto. La funzione di attivazione contestuale crea l'interfaccia utente del messaggio, che Gmail mostra all'utente.

Creare un componente aggiuntivo per i messaggi

Per aggiungere la funzionalità di messaggistica a un componente aggiuntivo, segui questi passaggi generali:

  1. Aggiungi i campi appropriati al manifest del progetto di script del componente aggiuntivo, inclusi gli ambiti richiesti per la funzionalità di messaggistica. Assicurati di aggiungere un campo di attivazione condizionale al manifest, con un valore unconditional di {}.
  2. Implementa una funzione di attivazione contestuale che crea una UI di messaggio quando l'utente seleziona il componente aggiuntivo in un messaggio.
  3. Implementa le funzioni associate necessarie per rispondere alle interazioni dell'utente con l'interfaccia utente.

Attivatori contestuali

Per fornire assistenza agli utenti durante la lettura dei messaggi, i componenti aggiuntivi possono definire un trigger contestuale nei manifest. Quando l'utente apre un messaggio di Gmail (con il componente aggiuntivo aperto) che soddisfa i criteri di attivazione*, l'attivatore si attiva. Un trigger attivato esegue una funzione di trigger contestuale che crea l'interfaccia utente del componente aggiuntivo e la restituisce per la visualizzazione in Gmail. A questo punto, l'utente può iniziare a interagire con il dispositivo.

I trigger contestuali sono definiti nel manifest del progetto del componente aggiuntivo. La definizione del trigger indica a Gmail quale funzione di trigger attivare e in quali condizioni. Ad esempio, questo snippet del manifest imposta un trigger incondizionato che chiama la funzione trigger onGmailMessageOpen() quando viene aperto un messaggio:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Funzione di attivazione contestuale

Ogni trigger contestuale deve avere una funzione di attivazione corrispondente che crea l'interfaccia utente del componente aggiuntivo. Specifichi questa funzione nel campo onTriggerFunction del manifest. Implementa questa funzione per accettare un argomento oggetto evento azione e restituire un singolo oggetto Card o un array di oggetti Card.

Quando viene attivato un trigger contestuale per un determinato messaggio Gmail, viene chiamata questa funzione e le viene passato un oggetto evento azione. Spesso le funzioni di attivazione utilizzano l'ID messaggio fornito da questo oggetto evento per ottenere il testo del messaggio e altri dettagli utilizzando il servizio Gmail di Apps Script. Nella maggior parte dei casi, devi attivare gli ambiti Gmail utilizzando il token di accesso fornito dall'oggetto evento e la funzione GmailApp.setCurrentMessageAccessToken(accessToken) prima di utilizzare altre funzioni del servizio Gmail. Ad esempio, la funzione trigger potrebbe estrarre i contenuti del messaggio utilizzando queste funzioni:

// Activate temporary Gmail scopes, in this case to allow
// the add-on to read message metadata and content.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);

// Read message metadata and content. This requires the Gmail scope
// https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
var subject = message.getSubject();
var sender = message.getFrom();
var body = message.getPlainBody();
var messageDate = message.getDate();

// Setting the access token with a gmail.addons.current.message.readonly
// scope also allows read access to the other messages in the thread.
var thread = message.getThread();
var threadMessages = thread.getMessages();

// Using this link can avoid the need to copy message or thread content
var threadLink = thread.getPermalink();

La funzione di attivazione può quindi agire su questi dati, estraendo le informazioni necessarie per l'interfaccia. Ad esempio, un componente aggiuntivo che riepiloga i numeri di vendita può raccogliere le cifre di vendita dal corpo del messaggio e organizzarle per la visualizzazione in una scheda.

La funzione di trigger deve creare e restituire un array di oggetti Card creati. Ad esempio, il seguente crea un componente aggiuntivo con una singola scheda che elenca solo l'oggetto e il mittente del messaggio:

function onGmailMessageOpen(e) {
  // Activate temporary Gmail scopes, in this case to allow
  // message metadata to be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();

  // Create a card with a single card section and two widgets.
  // Be sure to execute build() to finalize the card construction.
  var exampleCard = CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader()
          .setTitle('Example card'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}