Questa guida descrive in che modo le app Google Chat possono raccogliere ed elaborare informazioni degli utenti creando input dei moduli nelle interfacce basate su schede.
In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di Google Chat.
Le app di Chat richiedono informazioni agli utenti per eseguire azioni all'interno o al di fuori di Chat, ad esempio nei seguenti modi:
- Configura le impostazioni. Ad esempio, per consentire agli utenti di personalizzare le impostazioni di notifica o di configurare e aggiungere l'app Chat a uno o più spazi.
- Creare o aggiornare informazioni in altre applicazioni Google Workspace. Ad esempio, consenti agli utenti di creare un evento di Google Calendar.
- Consentire agli utenti di accedere e aggiornare le risorse in altre app o in altri servizi web. Ad esempio, un'app di Chat può aiutare gli utenti ad aggiornare lo stato di un ticket di assistenza direttamente da uno spazio di Chat.
Prerequisiti
Node.js
Un componente aggiuntivo di Google Workspace che funziona in Google Chat. Per crearne uno, compila la guida rapida HTTP.
Apps Script
Un componente aggiuntivo di Google Workspace che funziona in Google Chat. Per crearne uno, compila la guida rapida di Apps Script.
Creare moduli utilizzando le schede
Per raccogliere informazioni, le app di Chat progettano i moduli e i relativi input, e li inseriscono nelle schede. Per mostrare le schede agli utenti, le app di Chat possono utilizzare le seguenti interfacce di Chat:
- Messaggi di chat che contengono una o più schede.
- Dialoghi, ovvero schede che si aprono in una nuova finestra da messaggi e home page.
Le app di chat possono creare le schede utilizzando i seguenti widget:
Widget di input dei moduli che richiedono informazioni agli utenti. Se vuoi, puoi aggiungere la convalida ai widget di immissione dei moduli per assicurarti che gli utenti inseriscano e formattino correttamente le informazioni. Le app di chat possono utilizzare i seguenti widget di input dei moduli:
- Input di testo
(
textInput) per testo libero o suggerito. - Gli input di selezione
(
selectionInput) sono elementi dell'interfaccia utente selezionabili come caselle di controllo, pulsanti di opzione e menu a discesa. I widget di input di selezione possono anche compilare gli elementi da origini dati statiche o dinamiche. Ad esempio, gli utenti possono selezionare uno spazio di Chat di cui fanno parte da un elenco.
- Selettori data e ora
(
dateTimePicker) per le voci di data e ora.
- Input di testo
(
Un widget pulsante per consentire agli utenti di inviare i valori inseriti nella scheda. Dopo che un utente fa clic sul pulsante, l'app Chat può elaborare le informazioni che riceve.
Nell'esempio seguente, una scheda raccoglie i dati di contatto utilizzando un input di testo, un selettore della data e dell'ora e un input di selezione:
Per altri esempi di widget interattivi che puoi utilizzare per raccogliere informazioni, consulta Creare una scheda o una finestra di dialogo interattiva nella documentazione dell'API Google Chat.
Ricevere dati da widget interattivi
Ogni volta che gli utenti fanno clic su un pulsante, viene attivata l'azione corrispondente per le app di Chat con informazioni sull'interazione. In commonEventObject del payload dell'evento, l'oggetto formInputs contiene tutti i valori inseriti dall'utente.
Puoi recuperare i valori dall'oggetto
commonEventObject.formInputs.WIDGET_NAME, dove
WIDGET_NAME è il campo name specificato per il widget.
I valori vengono restituiti come tipo di dati specifico per il widget.
Di seguito è riportata una parte di un oggetto evento in cui un utente ha inserito valori per ciascun widget:
{
"commonEventObject": { "formInputs": {
"contactName": { "stringInputs": {
"value": ["Kai 0"]
}},
"contactBirthdate": { "dateInput": {
"msSinceEpoch": 1000425600000
}},
"contactType": { "stringInputs": {
"value": ["Personal"]
}}
}}
}
Per ricevere i dati, l'app di chat gestisce l'oggetto evento per ottenere i valori inseriti dagli utenti nei widget. La tabella riportata di seguito mostra come ottenere il valore di un determinato widget di input del modulo. Per ogni widget, la tabella mostra il tipo di dati accettato dal widget, dove viene memorizzato il valore nell'oggetto evento e un valore di esempio.
| Widget di input del modulo | Tipo di dati di input | Valore inserito dall'oggetto evento | Valore di esempio |
|---|---|---|---|
textInput |
stringInputs |
event.commonEventObject.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
Per ottenere il primo o l'unico valore, event.commonEventObject.formInputs.contactType.stringInputs.value[0] |
Personal |
dateTimePicker che accetta solo date. |
dateInput |
event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. |
1000425600000 |
Trasferire i dati su un'altra carta
Dopo che un utente ha inviato i dati di una carta, potresti dover restituire altre carte per eseguire una delle seguenti operazioni:
- Aiuta gli utenti a compilare moduli più lunghi creando sezioni distinte.
- Consenti agli utenti di visualizzare l'anteprima e confermare le informazioni della scheda iniziale, in modo che possano esaminare le loro risposte prima di inviarle.
- Compila dinamicamente le parti rimanenti del modulo. Ad esempio, per chiedere agli utenti di creare un appuntamento, un'app di chat potrebbe mostrare una scheda iniziale che richiede il motivo dell'appuntamento, quindi compilare un'altra scheda che fornisce gli orari disponibili in base al tipo di appuntamento.
Per trasferire l'input dei dati dalla scheda iniziale, puoi creare il widget button con actionParameters che contiene il name del widget e il valore inserito dall'utente, come mostrato nell'esempio seguente:
{
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submitForm",
"parameters": [
{
"key": "WIDGET_NAME",
"value": "USER_INPUT_VALUE"
},
// Can specify multiple parameters
]
}}
}]}
}
Dove WIDGET_NAME è il name del widget e USER_INPUT_VALUE è ciò che l'utente inserisce. Ad esempio, per un input di testo che raccoglie il nome di una persona, il nome del widget è contactName e un valore di esempio è Kai O.
Quando un utente fa clic sul pulsante, l'app Chat riceve un oggetto evento da cui puoi ricevere dati.
Rispondere a un invio di modulo
Dopo aver ricevuto i dati da un messaggio o una finestra di dialogo della scheda, l'app Chat risponde confermando la ricezione o generando un errore.
Nell'esempio seguente, un'app di chat invia un messaggio di testo per confermare di aver ricevuto correttamente un modulo inviato da un messaggio della scheda.
Node.js
/**
* Google Cloud Function that handles all Google Workspace Add On events for
* the contact manager app.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.contactManager = function contactManager(req, res) {
const chatEvent = req.body.chat;
const chatMessage = chatEvent.messagePayload.message;
// Handle MESSAGE events
if(chatEvent.messagePayload) {
return res.send(handleMessage(chatMessage, chatEvent.user));
// Handle CARD_CLICKED events
} else if(chatEvent.buttonClickedPayload) {
switch(req.body.commonEventObject.parameters.actionName) {
case "openDialog":
return res.send(openDialog());
case "openNextCard":
return res.send(openNextCard(req.body));
case "submitForm":
return res.send(submitForm(req.body));
}
}
};
/**
* Submits information from a dialog or card message.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Apps Script
/**
* Sends private text message that confirms submission.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Per elaborare e chiudere una finestra di dialogo, restituisci un oggetto
RenderActions
che specifica se vuoi inviare un messaggio di conferma, aggiornare
la scheda o il messaggio originale o semplicemente chiudere la finestra di dialogo. Per la procedura, consulta
Chiudere una finestra di dialogo.
Risoluzione dei problemi
Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.
Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.