Estensione dell'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 di Google Workspace 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

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 trigger contestuale corrispondente, 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:

  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 un'interfaccia utente del 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 di Google Workspace 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 a Gmail per la visualizzazione. A questo punto l'utente può iniziare a interagire con l'app.

I trigger contestuali sono definiti nel manifest del progetto del componente aggiuntivo. La definizione del trigger indica a Gmail quale funzione di trigger attivare in quali condizioni. Ad esempio, questo snippet del manifest imposta un attivatore incondizionato che chiama la funzione di attivazione 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. Ad esempio, la funzione trigger potrebbe estrarre il contenuto 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 trigger deve creare e restituire un array di oggetti Card creati. Ad esempio, il seguente codice crea un componente aggiuntivo con una sola 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.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }