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. In questo modo, i componenti aggiuntivi possono automatizzare le attività che rispondono ai contenuti dei messaggi, ad esempio visualizzare, recuperare o inviare 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 consiste nell'aprire un messaggio mentre il componente aggiuntivo è già aperto (ad esempio, quando si visualizza la home page del componente aggiuntivo nella finestra della posta in arrivo di Gmail). Il secondo consiste nell'avviare il componente aggiuntivo durante la visualizzazione di un messaggio.

In entrambi i casi, il componente aggiuntivo esegue la corrispondente funzione di trigger 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 trigger contestuale crea l'interfaccia utente dei messaggi per quel messaggio, che Gmail mostra all'utente.

Creare un componente aggiuntivo per i messaggi

Puoi aggiungere funzionalità di messaggistica a un componente aggiuntivo seguendo 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 trigger condizionale al manifest, con un unconditional valore di {}.
2. Implementa una funzione di trigger contestuale che crei un'interfaccia utente dei messaggi 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.

Trigger contestuali

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

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 di manifest imposta un trigger incondizionato che chiama la funzione di trigger onGmailMessageOpen() quando viene aperto un messaggio:

{
  ...
  "addOns": {

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

Funzione di trigger contestuale

Ogni trigger contestuale deve avere una funzione di trigger corrispondente che crei l'interfaccia utente del componente aggiuntivo. Specifica questa funzione nel campo onTriggerFunction del manifest. Implementa questa funzione in modo che accetti un argomento dell'oggetto evento azione e restituisca un singolo Cardo un array di Card.

Quando un trigger contestuale viene attivato per un determinato messaggio di Gmail, chiama questa funzione e le passa un oggetto evento azione. Spesso le funzioni di trigger 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's . Nella maggior parte dei casi, devi attivare gli ambiti di Gmail utilizzando il token di accesso fornito dall'oggetto evento e la GmailApp.setCurrentMessageAccessToken(accessToken) funzione prima di utilizzare altre funzioni del servizio Gmail. Ad esempio, la funzione di trigger potrebbe estrarre i contenuti dei messaggi 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 trigger 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 i dati di vendita dal corpo del messaggio e organizzarli per la visualizzazione in una scheda.

La funzione di trigger deve creare e restituire un array di oggetti creati Card. Ad esempio, il seguente codice 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];
}