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 Google Workspace di automatizzare le attività che rispondono ai contenuti dei messaggi, come la visualizzazione, il recupero o l'invio di informazioni aggiuntive relative al messaggio.
Accesso 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 consiste nell'aprire un messaggio mentre il componente aggiuntivo è già aperto (ad esempio, quando viene visualizzata la home page del componente aggiuntivo nella finestra della posta in arrivo di Gmail). Il secondo modo consiste nell'avviare il componente aggiuntivo mentre visualizzi un messaggio.
In entrambi i casi, il componente aggiuntivo esegue la funzione di attivazione contestuale corrispondente, definita nel relativo manifest. Il trigger viene eseguito anche se l'utente passa a un messaggio diverso mentre il componente aggiuntivo è ancora aperto. La funzione di trigger contestuale crea l'UI del messaggio per quel messaggio, che Gmail mostrerà all'utente.
Creare un componente aggiuntivo per i messaggi
Per aggiungere la funzionalità dei messaggi a un componente aggiuntivo, segui questi passaggi generali:
- Aggiungi i campi appropriati al manifest del progetto di script per i componenti aggiuntivi, inclusi gli ambiti richiesti per la funzionalità del messaggio. Assicurati di aggiungere un campo trigger condizionale al manifest, con un valore
unconditionalpari a{}. - Implementa una funzione di trigger contestuale che crea un'UI di messaggio quando l'utente seleziona il componente aggiuntivo in un messaggio.
- Implementa le funzioni associate necessarie per rispondere alle interazioni dell'utente con la UI.
Attivatori contestuali
Per fornire assistenza agli utenti durante la lettura dei messaggi, i componenti aggiuntivi di Google Workspace possono definire un attivatore contestuale nei loro file manifest. L'attivatore si attiva quando l'utente apre un messaggio di Gmail (con il componente aggiuntivo aperto) che soddisfa i criteri di attivazione*. Un attivatore attivato esegue una funzione di trigger contestuale che crea l'interfaccia utente del componente aggiuntivo e la restituisce per la visualizzazione da parte di Gmail. A quel punto l'utente può iniziare a interagire.
I trigger contestuali sono definiti nel manifest del progetto del componente aggiuntivo.
La definizione dell'attivatore indica a Gmail quale funzione di attivazione deve essere attivata in quali
condizioni. Ad esempio, questo snippet manifest imposta un trigger non condizionale che chiama la funzione trigger onGmailMessageOpen() quando viene aperto un messaggio:
{
...
"addOns": {
"common": {
...
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessageOpen"
}
],
...
},
...
}
...
}
Funzione di attivazione contestuale
Ogni attivatore contestuale deve avere una funzione attivatore corrispondente che crea l'interfaccia utente del componente aggiuntivo. Devi specificare questa funzione nel campo onTriggerFunction del file manifest. Implementi questa funzione per accettare un argomento oggetto evento azione e restituire un singolo oggetto Card o un array di oggetti Card.
Quando un attivatore contestuale si attiva per un determinato messaggio di Gmail, chiama questa funzione e la trasmette un oggetto evento azione. Spesso le funzioni di attivazione utilizzano l'ID messaggio fornito da questo oggetto evento per ricevere 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 trigger può quindi agire su questi dati, estraendo le informazioni necessarie per l'interfaccia. Ad esempio, un componente aggiuntivo che riassume i numeri delle vendite può raccogliere i dati di vendita dal corpo del messaggio e organizzarli per la visualizzazione in una scheda.
La funzione trigger deve creare e restituire un array di oggetti Card creati. Ad esempio, quanto segue crea un componente aggiuntivo con una singola scheda che elenca soltanto 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];
}