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 la visualizzazione, il recupero o l'invio di informazioni aggiuntive relative al messaggio.
Accesso all'interfaccia utente del messaggio del componente aggiuntivo
Esistono due modi per visualizzare l'interfaccia utente dei messaggi di un componente aggiuntivo. Il primo modo è aprire un messaggio quando 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 corrispondente funzione di trigger contestuale, definita nel manifest del componente aggiuntivo. L'attivatore viene eseguito anche se l'utente passa a un altro messaggio mentre il plug-in è ancora aperto. La funzione di attivazione contestuale genera l'interfaccia utente del messaggio, che viene poi visualizzata dall'utente in Gmail.
Creazione di un componente aggiuntivo per i messaggi
Per aggiungere la funzionalità di invio di messaggi a un componente aggiuntivo, segui questi passaggi generali:
- Aggiungi i campi appropriati al manifest del progetto dello script del componente aggiuntivo, inclusi gli scope necessari per la funzionalità dei messaggi. Assicurati di aggiungere un
campo di attivazione condizionale
al manifest, con un valore di
unconditional{}. - Implementa una funzione di trigger contestuale che genera un'interfaccia utente del messaggio quando l'utente seleziona il componente aggiuntivo in un messaggio.
- 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 di Google Workspace possono definire un attivatore contestuale nei manifest. Quando l'utente apre un messaggio di Gmail (con il componente aggiuntivo aperto) che soddisfa i criteri di attivazione*, l'attivatore viene attivato. Un attivatore attivato esegue una funzione di attivazione contestuale che costruisce 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.
Gli attivatori 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 attivatore incondizionato
che chiama la funzione di attivazione onGmailMessageOpen() quando viene aperto un messaggio:
{
...
"addOns": {
"common": {
...
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessageOpen"
}
],
...
},
...
}
...
}Funzione di trigger contestuale
Ogni attivatore contestuale deve avere una funzione di attivazione corrispondente che costruisce l'interfaccia utente del componente aggiuntivo. Devi specificare questa funzione nel
campo onTriggerFunction
del manifest. Implementa questa funzione per accettare un
argomento
oggetto evento di azione
e restituire un singolo
oggetto
Card o un array di
oggetti
Card.
Quando viene attivato un attivatore contestuale per un determinato messaggio di Gmail, viene chiamata questa funzione e viene passato un oggetto evento di azione. Spesso le funzioni di attivazione utilizzano l'ID messaggio fornito da questo oggetto evento per recuperare il testo del messaggio e altri dettagli utilizzando il servizio Gmail di Apps Script. Ad esempio, la funzione di attivazione 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 attivazione può quindi intervenire su questi dati, estraendo le informazioni di cui ha bisogno per l'interfaccia. Ad esempio, un componente aggiuntivo che riassume i numeri di vendita può raccogliere i dati sulle vendite dal corpo del messaggio e organizzarli per la visualizzazione in una scheda.
La funzione di trigger deve creare e restituire un array di oggetti
Card
costruiti. Ad esempio, il codice 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.newKeyValue()
.setTopLabel('Subject')
.setContent(subject))
.addWidget(CardService.newKeyValue()
.setTopLabel('From')
.setContent(sender)))
.build(); // Don't forget to build the Card!
return [exampleCard];
}