Raccogliere ed elaborare informazioni degli utenti di Google Chat

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 all'esterno 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

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 e suggerire elementi dai dati di Google Workspace (ad esempio uno spazio di Chat) o da un'origine dati dinamica. Per maggiori dettagli, consulta la sezione Aggiungere un menu a selezione multipla.

  • Selettori data e ora (dateTimePicker) per le voci di data e ora.

• 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.

Aggiungere un menu di multiselezione

Per personalizzare gli elementi di selezione o consentire agli utenti di selezionarli da un'origine dati dinamica, le app di Chat possono utilizzare i menu di selezione multipla, un tipo di widgetSelectionInput. Ad esempio, la seguente scheda mostra un menu di selezione multipla in cui gli utenti possono selezionare dinamicamente un elenco di contatti:

Puoi compilare gli elementi di un menu a più scelte dalle seguenti origini dati:

• Dati di Google Workspace, che includono gli utenti o gli spazi di Chat di cui l'utente è membro. Il menu compila solo gli elementi della stessa organizzazione Google Workspace.
• Origini dati esterne, ad esempio un database relazionale. Ad esempio, puoi utilizzare i menu di selezione multipla per aiutare un utente a scegliere tra un elenco di lead di vendita di un sistema di gestione dei rapporti con i clienti (CRM).

Compilare gli elementi da un'origine dati Google Workspace

Per utilizzare le origini dati di Google Workspace, specifica il campo platformDataSource nel widget SelectionInput. A differenza di altri tipi di input di selezione, devi ommettere gli oggetti SelectionItem, perché questi elementi di selezione vengono ricavati dinamicamente da Google Workspace.

Il seguente codice mostra un menu di selezione multipla degli utenti di Google Workspace. Per compilare gli utenti, l'input di selezione imposta commonDataSource su USER:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Il seguente codice mostra un menu di selezione multipla degli spazi di Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource. Il menu di multiselezione imposta anche defaultToCurrentSpace su true, il che rende lo spazio corrente la selezione predefinita nel menu:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Compilare gli elementi da un'origine dati esterna

I menu a selezione multipla possono anche compilare gli elementi di un'origine dati di terze parti o esterna. Per utilizzare un'origine dati esterna, specifica il campo externalDataSource nel widget SelectionInput che contiene la funzione che esegue query e restituisce gli elementi dall'origine dati.

Per ridurre le richieste a un'origine dati esterna, puoi includere gli elementi suggeriti che vengono visualizzati nel menu di selezione multipla prima che gli utenti inizino a digitare. Ad esempio, puoi compilare i contatti cercati di recente per l'utente. Per compilare gli elementi suggeriti da un'origine dati esterna, specifica oggetti statici SelectionItem.

Il codice seguente mostra un menu di selezione multipla che esegue query e compila gli elementi da un'origine dati esterna:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

Sostituisci FUNCTION con l'URL HTTP o con il nome della funzione di Apps Script che esegue query sul database esterno. Per un esempio completo che mostra come restituire gli elementi suggeriti, consulta la sezione Suggerire elementi con più opzioni di selezione.

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.

Dopo aver ricevuto i dati, l'app di Chat può eseguire una delle seguenti operazioni:

• Per le schede che contengono un menu a più opzioni, compila o suggerisci gli elementi in base a ciò che l'utente digita nel menu.
• Trasferisci i dati in un'altra scheda, in modo che l'utente possa rivedere le sue informazioni o passare alla sezione successiva del modulo.
• Rispondi all'utente per confermare che ha completato correttamente il modulo.

Suggerire elementi con selezione multipla

Se una scheda contiene un menu di selezione multipla che compila gli elementi di un'origine dati esterna, l'app Chat può restituire gli elementi suggeriti in base a ciò che gli utenti digitano nel menu. Ad esempio, se un utente inizia a digitare Atl per un menu che mostra le città degli Stati Uniti, la tua app Chat può suggerire automaticamente Atlanta prima che l'utente finisca di digitare. L'app Chat può suggerire fino a 100 elementi.

Per suggerire e compilare dinamicamente gli elementi in un menu di selezione multipla, il widget SelectionInput nella scheda deve specificare una funzione che esegue query sull'origine dati esterna. Per restituire gli elementi suggeriti, la funzione deve:

1. Gestisci un oggetto evento, che l'app Chat riceve quando gli utenti digitano nel menu.
2. Dall'oggetto evento, recupera il valore digitato dall'utente, rappresentato nel campo event.commonEventObject.parameters["autocomplete_widget_query"].
3. Esegui una query sull'origine dati utilizzando il valore inserito dall'utente per ottenere uno o più SelectionItems da suggerire all'utente.
4. Restituire gli elementi suggeriti restituendo l'azione RenderActions con un oggetto modifyCard.

Il seguente esempio di codice mostra come un'app Chat suggerisca dinamicamente gli elementi nel menu di selezione multipla di una scheda. Quando un utente digita nel menu, la funzione o l'endpoint fornito nel campo externalDataSource del widget esegue una query su un'origine dati esterna e suggerisce gli elementi che l'utente può selezionare.

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

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 una finestra di dialogo o da un messaggio 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.

/**
 * 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 payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } 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."
  }}}}};
}

/**
 * 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.